kcpp / ICPP  -  the Internet C++ compiler and interpreter  (x86 drop)
====================================================================

Copyright (c) 2026 Muhammad Anisur Rahman.  MIT License - see LICENSE.

kcpp is a C/C++ compiler toolchain. ICPP is a scripting language embedded in
it: C syntax you already know, plus one new thing - a '$var' typeless variable.
There is exactly ONE interpreter; icpp.exe is a small launcher for it.

This is a 32-bit (x86) build.


INSTALL
-------
    install.bat                     prompts for a directory (default C:\kcpp)
    install.bat D:\kcpp             install to a specific directory
    install.bat D:\kcpp /nopath     install without touching PATH
    install.bat D:\kcpp /system     register on the SYSTEM PATH (needs admin)

By default <home>\bin is added to your PER-USER PATH; no administrator rights
are needed. Open a new command prompt afterwards for it to take effect.


QUICK START
-----------
    icpp examples\language\01_core_language.icpp

    icpp yourscript.icpp            run a script
    kcpp -icpp yourscript.icpp      the same thing, spelled out
    kcpp -icpp -rtl yourscript.icpp translate to Verilog instead of running

icpp.exe forwards every argument to kcpp, so any kcpp flag works through it.


WHAT IS IN bin\
---------------
  kcpp.exe      the compiler + the ICPP interpreter
  icpp.exe      launcher: runs kcpp with -icpp, forwards args and exit code
  klink.exe     linker      (.o + .lib  ->  .kx executable)
  khex16.exe    hex/image generator
  kice.exe      in-circuit-emulator front end
  isqldll.dll   the ISQL engine - REQUIRED, see below

  IMPORTANT: isqldll.dll must stay beside kcpp.exe. ICPP's icpp_sql_* builtins
  link to it at LOAD time, so without it kcpp.exe produces NO OUTPUT and exits
  0 - no error message at all. If kcpp seems to do nothing, this is why.


EXAMPLES
--------
  examples\language\   the conformance suite, which doubles as a tour of the
                       language: core syntax, strings, lists/maps, sets,
                       dictionaries, tuples, the #include library system,
                       file I/O, bits/hex. Each file self-checks and prints
                       a pass/fail count, so you can run them all and see
                       exactly what the interpreter guarantees.
                       Start with 01_core_language.icpp.

  examples\html\       ICPP embedded in HTML via <?icpp ?>, as served by
                       iwebserver or Apache CGI - including live ISQL query
                       pages, image matching and RECOGNIZE demos.

  examples\llm\        the ICPP-hosted language-model material: icpp_llm.c
                       (the LLM API), llm_chat_check.c and llmtrace_check.c.
                       llmtrace shows the model's internals step by step,
                       which is the point of it for teaching - you can watch
                       a small statistical model make each prediction rather
                       than treat it as a black box.
                       NOTE: ICPP scripts here still use the .c extension;
                       renaming them to .icpp is a pending change.

  examples\fpga\       ex1..ex6, the FPGA flow: counter, synthesis, fit,
                       route, bitstream, execute.

  lib\stringutil.icpp  an includable ICPP library; see the library section of
                       the manual for the //@icpp-* manifest tags.


DOCUMENTATION
-------------
  doc\ICPP_USER_MANUAL.md      the full language and builtin reference
  doc\_icpp_builtins_list.txt  every registered builtin, one per line


KNOWN LIMITATIONS (stated deliberately)
---------------------------------------
- miskasm (the assembler) is NOT in this drop. It does not currently build
  with the shipping toolset: SYMTAB.C defines InsertInstruction twice - a
  4-parameter version and a 12-parameter version disabled behind '#if 0' -
  while Parse.c calls it with both arities. Older compilers accepted the
  mismatch; current ones reject it. Until that is resolved, the
  compile-to-hardware chain (kcpp -> miskasm -> klink -> khex16/kice) cannot
  be completed from this package. ICPP scripting is unaffected.
- Two known interpreter issues, both covered by the conformance suite's
  90_known_issues.icpp: the ternary false-branch returns the wrong value,
  and regex backreferences (\N) do not substitute.
- ICPP runs single-threaded. ithread_create is limited to external commands.
