konpeito 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 453b0bb32e4ef66b8b6020d262200e070caf01fb483cff4a0ebd6ceba46495b3
-  data.tar.gz: 7b38fb2807e1649150a0febae5defcb8f964967a715770db1de857d6409f88b3
+  metadata.gz: 50ad4b5d35d1b8abd26ee9d941a901b99e281eb9cc7d2deed777f3ebf12b2308
+  data.tar.gz: fc91a16a60718a8a910776ab56f01a09d49ec2ee78e71082965392f1dee332e1
 SHA512:
-  metadata.gz: afa5fd10db773c8e1bb3c399a39cf140b1c7577271420750368551ee80cab864683d9455860ddba185b0d53cc221df42b5beb3a7334fbc67b56747e4a7bd6e0f
-  data.tar.gz: 7fbe956b09d489f9af313c0fa6600f81960cb02cb72d95f912a4d50d9f658b4b7bff35528d43b73c223d011d0aa5c35f6c63bf09ce5f1873c14605cd7274395e
+  metadata.gz: c2efa11a609aba145beef6d2b722028f657a6a4d5469864241cbdde1b43dc494b9cf814379788a8ede8d4715d0aceab76df3d64a1c6b14913a3e2f84d0787f1f
+  data.tar.gz: 77860386e45ac9a5b78ead9b0f02dfc3d759668fe5ffc3d97c72c4932ca297778d27192c6a698ad264f7641a988b07905dbf6a15c32f10320678999e89a604dc

data/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-03-14
+
+### Added
+- **KUI declarative UI framework**: Pure Ruby DSL for building GUI/TUI apps with a single codebase. Wraps Clay+Raylib (GUI) or ClayTUI (TUI). Widgets: `vpanel`, `hpanel`, `fixed_panel`, `label`, `label_num`, `button`, `menu_item`, `spacer`, `divider`, `progress_bar`. Theme system and unified key event abstraction.
+- **ClayTUI stdlib**: Terminal UI backend using Clay layout engine + termbox2 rendering. Auto-detected via `ClayTUI` module reference.
+- **KonpeitoShell stdlib**: Shell execution (`exec`, `system`), environment variables (`getenv`, `setenv`), and file I/O (`read_file`, `write_file`, `append_file`, `file_exists`) for mruby backend.
+- **RPG framework stdlib**: Reusable RPG game components (tilemap, sprites, camera, battle system) for raylib-based games.
+- **Stdlib auto-detection expansion**: `KonpeitoJSON`, `KonpeitoHTTP`, `KonpeitoCrypto`, `KonpeitoCompression` added to `STDLIB_MODULE_MAP` for automatic RBS injection when referenced in source code.
+- **KUI auto-path resolution**: `require "kui_gui"` / `require "kui_tui"` works without `-I` flags — KUI stdlib directory is automatically included in compiler search paths.
+- **KUI example apps**: Counter (GUI + TUI), minimal hello, multi-page dashboard with sidebar navigation.
+- **DQ RPG demo with Clay UI**: Battle scenes, shop menus, and status displays using Clay layout integration.
+- Keyword arguments documented as supported in mruby backend.
+
+### Fixed
+- **mruby GC crash in native callbacks**: `rb_block_call` stored raw C stack pointer (`data2`) in proc env — GC tried to dereference it as `RBasic*` causing crash in `gc_mark_children`. Fixed by storing `mrb_nil_value()` instead; the native callback path reads `data2` from a global, not from proc env.
+- **TUI rendering flicker**: Added per-frame string pool to `clay_tui_native.c` (64KB static buffer) to prevent Clay from holding pointers to GC-managed mruby heap memory that could be invalidated between frames.
+- **Documentation references**: Fixed CLAUDE.md referencing non-existent `docs/architecture.md`.
+
+### Changed
+- Tutorials (EN/JA) updated with KUI framework sections and all stdlib module documentation (Shell, JSON, HTTP, Crypto, Compression).
+
+## [0.6.0] - 2026-03-11
+
+### Added
+- **Raylib stdlib expansion**: 119 new cfunc bindings (87 → 206 total) for 2D RPG/SLG game development
+  - Texture/Sprite management (10): load, unload, draw, draw_rec, draw_pro, draw_scaled, dimensions, validity check
+  - Audio — Sound (10): load, unload, play, stop, pause, resume, playing?, volume, pitch
+  - Audio — Music (13): load, unload, play, stop, pause, resume, update, playing?, volume, pitch, time_length, time_played, seek
+  - Audio — Device (4): init, close, ready?, master volume
+  - Camera2D (4): begin/end mode, world-to-screen coordinate conversion (x/y)
+  - File I/O (4): save/load text files, file/directory existence checks
+  - Font management (6): load, load_ex, unload, draw_text_ex, measure_text_ex (x/y)
+  - Gamepad input (7 + 21 constants): button pressed/down/released/up, axis movement/count, D-pad/face/trigger/middle button and axis constants
+  - Extended shapes (5): draw_rectangle_pro, draw_rectangle_rounded, gradient v/h, circle sector
+  - Collision detection (5): recs, circles, circle-rec, point-rec, point-circle
+  - ID table pattern for resource management: textures (256), sounds (128), music (32), fonts (32)
+- **RPG tilemap demo**: `examples/mruby_rpg_demo/rpg_demo.rb` — 40×40 tilemap, smooth camera scrolling, 4-direction player movement with animation, sign interaction, HUD with step counter
+- macOS audio framework linker flags (CoreAudio, AudioToolbox, CoreFoundation)
+
+### Fixed
+- **Inliner CFuncCall bug**: `clone_and_rename()` now handles `CFuncCall`, `ExternConstructorCall`, and `ExternMethodCall` — parameters are correctly remapped when user functions calling `@cfunc` are inlined (previously fell through to default case, returning instructions with unmapped parameters)
+- **CI lint**: use anonymous block forwarding (`&`) in `rbs_loader.rb`
+- **CI test isolation**: use unique symbol names in `module_native_array_test` to avoid ELF symbol interposition on Linux
+
 ## [0.5.0] - 2026-03-10
 
 ### Added

data/lib/konpeito/codegen/inliner.rb

@@ -542,6 +542,40 @@ module Konpeito
             result_var: new_result
           )
 
+        when HIR::CFuncCall
+          new_result = inst.result_var ? prefix + inst.result_var : nil
+          new_args = inst.args.map { |a| transform_value(a, prefix, param_map) }
+          HIR::CFuncCall.new(
+            c_func_name: inst.c_func_name,
+            args: new_args,
+            cfunc_type: inst.cfunc_type,
+            result_var: new_result
+          )
+
+        when HIR::ExternConstructorCall
+          new_result = inst.result_var ? prefix + inst.result_var : nil
+          new_args = inst.args.map { |a| transform_value(a, prefix, param_map) }
+          HIR::ExternConstructorCall.new(
+            extern_type: inst.extern_type,
+            c_func_name: inst.c_func_name,
+            args: new_args,
+            method_sig: inst.method_sig,
+            result_var: new_result
+          )
+
+        when HIR::ExternMethodCall
+          new_result = inst.result_var ? prefix + inst.result_var : nil
+          new_receiver = transform_value(inst.receiver, prefix, param_map)
+          new_args = inst.args.map { |a| transform_value(a, prefix, param_map) }
+          HIR::ExternMethodCall.new(
+            receiver: new_receiver,
+            c_func_name: inst.c_func_name,
+            args: new_args,
+            extern_type: inst.extern_type,
+            method_sig: inst.method_sig,
+            result_var: new_result
+          )
+
         else
           # For other instructions, just return as-is with renamed result
           inst

data/lib/konpeito/codegen/llvm_generator.rb

@@ -69,7 +69,7 @@ module Konpeito
         end
       end
 
-      attr_reader :profiler, :variadic_functions, :alias_renamed_methods
+      attr_reader :profiler, :variadic_functions, :keyword_param_functions, :alias_renamed_methods
 
       def generate(hir_program)
         @hir_program = hir_program
@@ -1126,6 +1126,17 @@ module Konpeito
         init_builder.store(init_builder.call(mrb_undef_fn), @mrb_qundef_global)
         init_builder.ret_void
 
+        # GC arena management functions (prevent arena overflow in loops)
+        @konpeito_gc_arena_save = @mod.functions.add(
+          "konpeito_gc_arena_save", [], LLVM::Int32
+        )
+        @konpeito_gc_arena_restore = @mod.functions.add(
+          "konpeito_gc_arena_restore", [LLVM::Int32], LLVM.Void
+        )
+        @konpeito_gc_protect_value = @mod.functions.add(
+          "konpeito_gc_protect_value", [value_type], LLVM.Void
+        )
+
         # Clear @qnil etc. so the accessor methods know to load from globals
         @qnil = nil
         @qtrue = nil
@@ -1728,6 +1739,16 @@ module Konpeito
           end
         end
 
+        # For mruby: save GC arena index so we can restore before return.
+        # This prevents arena overflow when LLVM functions call each other
+        # directly (bypassing mruby dispatch's arena management).
+        @mruby_gc_arena_alloca = nil
+        if @runtime == :mruby
+          @mruby_gc_arena_alloca = @builder.alloca(LLVM::Int32, "_gc_arena")
+          arena_idx = @builder.call(@konpeito_gc_arena_save)
+          @builder.store(arena_idx, @mruby_gc_arena_alloca)
+        end
+
         # Insert profiling entry probe after parameter setup
         insert_profile_entry_probe(hir_func)
 
@@ -1753,6 +1774,21 @@ module Konpeito
         func
       end
 
+      # Emit a return instruction with mruby GC arena management.
+      # For the mruby backend, restores the arena to the saved index and
+      # protects the return value from GC before returning.
+      def emit_ret(value)
+        if @mruby_gc_arena_alloca
+          idx = @builder.load2(LLVM::Int32, @mruby_gc_arena_alloca, "_arena_r")
+          @builder.call(@konpeito_gc_arena_restore, idx)
+          # Protect the return value so it survives the arena restore
+          if value.type == value_type
+            @builder.call(@konpeito_gc_protect_value, value)
+          end
+        end
+        @builder.ret(value)
+      end
+
       # Topologically sort blocks based on phi dependencies
       # Ensures blocks are generated after the blocks their phi nodes reference
       def sort_blocks_by_phi_dependencies(blocks)
@@ -4843,6 +4879,9 @@ module Konpeito
         saved_allocas = @variable_allocas.dup
         saved_in_block_callback = @in_block_callback
         saved_block_callback_self = @block_callback_self
+        saved_mrb_cache = save_mrb_constant_cache
+        saved_current_function = @current_function
+        saved_gc_arena_alloca = @mruby_gc_arena_alloca
 
         # Create entry block for callback
         entry = callback_func.basic_blocks.append("entry")
@@ -4850,10 +4889,16 @@ module Konpeito
 
         # Reset variable tracking for callback scope.
         # Set @in_block_callback so nested proc creation uses GC-safe escape-cells mode.
+        # Reset mruby constant cache — LLVM values are scoped per function, so
+        # cached %qnil/%qtrue from the parent function are invalid here.
+        # Clear GC arena alloca — callbacks don't own their own arena scope.
         @in_block_callback = true
+        @mruby_gc_arena_alloca = nil
         @variables = {}
         @variable_types = {}
         @variable_allocas = {}
+        reset_mrb_constant_cache
+        @current_function = callback_func
 
         # Setup captured variable access through data2 pointer
         unless captures.empty?
@@ -5132,6 +5177,9 @@ module Konpeito
         @variable_allocas = saved_allocas
         @in_block_callback = saved_in_block_callback
         @block_callback_self = saved_block_callback_self
+        restore_mrb_constant_cache(saved_mrb_cache)
+        @current_function = saved_current_function
+        @mruby_gc_arena_alloca = saved_gc_arena_alloca
 
         callback_func
       end
@@ -5583,6 +5631,7 @@ module Konpeito
         saved_block_callback_self = @block_callback_self
         saved_in_thread_callback = @in_thread_callback
         saved_thread_boxed_vars = @thread_boxed_vars
+        saved_gc_arena_alloca = @mruby_gc_arena_alloca
 
         # Create entry block for callback
         entry = callback_func.basic_blocks.append("entry")
@@ -5599,6 +5648,7 @@ module Konpeito
         @in_block_callback = false
         @block_callback_self = nil
         @in_thread_callback = true
+        @mruby_gc_arena_alloca = nil
 
         unless captures.empty?
           declare_free
@@ -5735,6 +5785,7 @@ module Konpeito
         @block_callback_self = saved_block_callback_self
         @in_thread_callback = saved_in_thread_callback
         @thread_boxed_vars = saved_thread_boxed_vars
+        @mruby_gc_arena_alloca = saved_gc_arena_alloca
 
         callback_func
       end
@@ -8134,11 +8185,13 @@ module Konpeito
         saved_block_callback_self = @block_callback_self
         saved_rescue_escape_array = @rescue_escape_array
         saved_rescue_escape_indices = @rescue_escape_indices
+        saved_gc_arena_alloca = @mruby_gc_arena_alloca
 
         # Reset variable tracking for callback scope
         @variables = {}
         @variable_types = {}
         @variable_allocas = {}
+        @mruby_gc_arena_alloca = nil
 
         if try_hir_blocks && !try_hir_blocks.empty?
           # Structured try body: process HIR BasicBlock list (handles control flow inside try).
@@ -8231,6 +8284,7 @@ module Konpeito
         @block_callback_self = saved_block_callback_self
         @rescue_escape_array = saved_rescue_escape_array
         @rescue_escape_indices = saved_rescue_escape_indices
+        @mruby_gc_arena_alloca = saved_gc_arena_alloca
 
         callback_func
       end
@@ -8252,6 +8306,7 @@ module Konpeito
         saved_block_callback_self = @block_callback_self
         saved_rescue_escape_array = @rescue_escape_array
         saved_rescue_escape_indices = @rescue_escape_indices
+        saved_gc_arena_alloca = @mruby_gc_arena_alloca
 
         # In normal mode: params[0] = self. In escape mode, set @block_callback_self after unpacking.
         @block_callback_self = callback_func.params[0] unless escape_var_names
@@ -8264,6 +8319,7 @@ module Konpeito
         @variables = {}
         @variable_types = {}
         @variable_allocas = {}
+        @mruby_gc_arena_alloca = nil
 
         # CRuby rescue callback: (VALUE data2, VALUE exception)
         exception_val = callback_func.params[1]
@@ -8393,6 +8449,7 @@ module Konpeito
         @block_callback_self = saved_block_callback_self
         @rescue_escape_array = saved_rescue_escape_array
         @rescue_escape_indices = saved_rescue_escape_indices
+        @mruby_gc_arena_alloca = saved_gc_arena_alloca
 
         callback_func
       end
@@ -8532,6 +8589,7 @@ module Konpeito
         @block_callback_self = saved_block_callback_self
         @rescue_escape_array = saved_rescue_escape_array
         @rescue_escape_indices = saved_rescue_escape_indices
+        @mruby_gc_arena_alloca = saved_gc_arena_alloca
 
         callback_func
       end
@@ -9593,9 +9651,9 @@ module Konpeito
             value, type_tag = get_value_with_type(term.value)
             # Box the value before returning to Ruby
             boxed = convert_value(value, type_tag, :value)
-            @builder.ret(boxed)
+            emit_ret(boxed)
           else
-            @builder.ret(qnil)
+            emit_ret(qnil)
           end
         when HIR::Branch
           condition, cond_type = get_value_with_type(term.condition)

data/lib/konpeito/codegen/mruby_backend.rb

@@ -8,6 +8,10 @@ module Konpeito
   module Codegen
     # Generates standalone executable from LLVM module using mruby runtime
     class MRubyBackend
+      # Stdlib modules that should be auto-defined in mruby init code
+      # even when no ModuleDef exists in HIR (cfunc-only modules).
+      STDLIB_MODULES = %w[Raylib Clay ClayTUI KonpeitoShell].freeze
+
       attr_reader :llvm_generator, :output_file, :module_name, :rbs_loader, :debug
 
       def initialize(llvm_generator, output_file:, module_name: nil, rbs_loader: nil, debug: false, extra_c_files: [],
@@ -62,6 +66,10 @@ module Konpeito
           clay_objs = ensure_clay_compiled
           extra_obj_files.concat(clay_objs)
 
+          # Compile vendored termbox2 library if ClayTUI is used
+          tb2_objs = ensure_termbox_compiled
+          extra_obj_files.concat(tb2_objs)
+
           obj_files = [obj_file, init_obj_file, helpers_obj_file] + extra_obj_files
 
           # Link into standalone executable
@@ -278,7 +286,9 @@ module Konpeito
         lines << ""
 
         # Define modules
+        defined_module_names = []
         hir.modules.each do |module_def|
+          defined_module_names << module_def.name.to_s
           module_var = "m#{module_def.name}"
           lines << "    struct RClass *#{module_var} = mrb_define_module(mrb, \"#{module_def.name}\");"
 
@@ -319,6 +329,18 @@ module Konpeito
           end
         end
 
+        # Auto-define stdlib modules that have cfunc methods but no ModuleDef in HIR.
+        # This ensures that even if a dynamic dispatch fallback occurs (e.g., due to
+        # a method name mismatch), the module constant exists at runtime.
+        if @rbs_loader
+          STDLIB_MODULES.each do |mod_name|
+            next if defined_module_names.include?(mod_name)
+            next unless @rbs_loader.has_cfunc_methods?(mod_name.to_sym)
+
+            lines << "    mrb_define_module(mrb, \"#{mod_name}\");"
+          end
+        end
+
         # Define NativeClasses with mrb_data_type
         native_classes.each do |class_name, class_type|
           lines.concat(generate_native_class_init(class_name, class_type))
@@ -434,8 +456,21 @@ module Konpeito
         else
           arity = llvm_func.params.size - 1  # Subtract self
 
+          # Check if this function has only keyword args (no positional params).
+          # If so, the kwargs hash arg is optional — caller may pass 0 args
+          # when no keywords are specified (e.g., `footer do ... end`).
+          func_base_name = mangled_name.sub(/\Arn_/, "")
+          kw_info = llvm_generator.keyword_param_functions[func_base_name] ||
+                    llvm_generator.keyword_param_functions[func_base_name.to_sym]
+          kwargs_only = kw_info && kw_info[:regular_count] == 0 && arity == 1
+
           lines << "static mrb_value #{wrapper_name}(mrb_state *mrb, mrb_value self) {"
-          if arity > 0
+          if kwargs_only
+            # Single optional kwargs hash arg — default to empty hash
+            lines << "    mrb_value a0 = mrb_nil_value(), _block = mrb_nil_value();"
+            lines << "    mrb_get_args(mrb, \"|o&\", &a0, &_block);"
+            lines << "    if (mrb_nil_p(a0)) a0 = mrb_hash_new(mrb);"
+          elsif arity > 0
             lines << "    mrb_value #{(0...arity).map { |i| "a#{i}" }.join(', ')}, _block;"
             format_str = "o" * arity + "&"
             args_list = (0...arity).map { |i| "&a#{i}" }.join(", ") + ", &_block"
@@ -933,6 +968,36 @@ module Konpeito
           )
         end
 
+        # Include termbox2 if ClayTUI is used
+        clay_tui_used = @extra_c_files.any? { |f| File.basename(f).include?("clay_tui") }
+        if clay_tui_used
+          sections << license_section(
+            "termbox2",
+            "MIT",
+            "Copyright (c) 2021 termbox developers",
+            "https://github.com/termbox/termbox2",
+            <<~MIT
+              Permission is hereby granted, free of charge, to any person obtaining a copy
+              of this software and associated documentation files (the "Software"), to deal
+              in the Software without restriction, including without limitation the rights
+              to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+              copies of the Software, and to permit persons to whom the Software is
+              furnished to do so, subject to the following conditions:
+
+              The above copyright notice and this permission notice shall be included in all
+              copies or substantial portions of the Software.
+
+              THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+              IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+              FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+              AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+              LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+              OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+              SOFTWARE.
+            MIT
+          )
+        end
+
         # Include raylib if linked
         ffi_libs = @rbs_loader&.all_ffi_libraries || []
         if ffi_libs.any? { |lib| lib.to_s.include?("raylib") }
@@ -1171,7 +1236,9 @@ module Konpeito
         # Known framework dependencies for popular libraries
         case lib_name
         when "raylib"
-          ["-framework", "IOKit", "-framework", "Cocoa", "-framework", "OpenGL"]
+          ["-framework", "IOKit", "-framework", "Cocoa", "-framework", "OpenGL",
+           "-framework", "CoreAudio", "-framework", "AudioToolbox",
+           "-framework", "CoreFoundation"]
         when "SDL2", "sdl2"
           ["-framework", "IOKit", "-framework", "Cocoa", "-framework", "Carbon",
            "-framework", "CoreAudio", "-framework", "AudioToolbox",
@@ -1218,15 +1285,46 @@ module Konpeito
         [clay_impl_obj]
       end
 
+      # Compile vendored termbox2 implementation if ClayTUI stdlib is used
+      # Returns array of object file paths
+      def ensure_termbox_compiled
+        clay_tui_used = @extra_c_files.any? { |f| File.basename(f).include?("clay_tui") }
+        return [] unless clay_tui_used
+
+        tb2_dir = File.expand_path("../../../vendor/termbox2", __dir__)
+        tb2_impl_c = File.join(tb2_dir, "termbox2_impl.c")
+        tb2_impl_obj = File.join(tb2_dir, "termbox2_impl.o")
+
+        return [] unless File.exist?(tb2_impl_c)
+
+        cc, cc_flags = cross_cc_with_flags
+
+        # Compile termbox2_impl.c (only if stale)
+        unless File.exist?(tb2_impl_obj) && File.mtime(tb2_impl_obj) > File.mtime(tb2_impl_c)
+          cmd = [*cc, "-c", "-O2"]
+          cmd.concat(cc_flags)
+          cmd += ["-o", tb2_impl_obj, tb2_impl_c]
+          system(*cmd) or return []
+        end
+
+        [tb2_impl_obj]
+      end
+
       def ffi_include_flags
         flags = []
 
-        # Always add vendored Clay include path if Clay stdlib is used
+        # Always add vendored Clay include path if Clay/ClayTUI stdlib is used
         clay_dir = File.expand_path("../../../vendor/clay", __dir__)
         if @extra_c_files.any? { |f| File.basename(f).include?("clay") } && Dir.exist?(clay_dir)
           flags << "-I#{clay_dir}"
         end
 
+        # Add vendored termbox2 include path if ClayTUI stdlib is used
+        tb2_dir = File.expand_path("../../../vendor/termbox2", __dir__)
+        if @extra_c_files.any? { |f| File.basename(f).include?("clay_tui") } && Dir.exist?(tb2_dir)
+          flags << "-I#{tb2_dir}"
+        end
+
         if cross_compiling?
           # When cross-compiling, use cross library include paths
           flags << "-I#{@cross_libs_dir}/../include" if @cross_libs_dir && Dir.exist?("#{@cross_libs_dir}/../include")