kcpp / ICPP  -  the Internet C++ compiler and interpreter
========================================================
1.0.0+272c682   built 2026-08-29

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 is a small launcher for it.


WHAT IS IN THIS DROP
--------------------
    windows-x64\bin\    kcpp.exe, icpp.exe, klink.exe, klib.exe, khex16.exe,
                         kice.exe, isqldll.dll
    linux-x64/bin/       kcpp, icpp, klink, klib, khex16, kice
    linux-x64/lib/       libisqldll.so.1  (+ libisqldll.so link, .tar.gz only)
    doc/                 ICPP_USER_MANUAL.md, ICPP_MANUAL.md, builtin list
    examples/            language / html / llm / fpga samples
    lib/                 ICPP libraries (stringutil.icpp)
    tools/               icpplint.py - checks a script against the $var
                         conventions in ICPP_MANUAL.md chapter 3

Both platforms are 64-bit, and both report the same version, because the
version is keyed to the source commit rather than to the build clock.

THE 32-BIT BUILD IS DISCONTINUED. The previous drop
(KCPP_ICPP_x86_2026-08-09.zip) was 32-bit and is no longer produced.

Take the .tar.gz on Linux, not the .zip: zip carries neither the executable
bit nor the symlink that libisqldll.so.1 is loaded through.

LINUX REQUIREMENTS
    glibc 2.36 or newer   (built on Debian 12; older systems will not load it)
    OpenSSL 3             libssl.so.3 and libcrypto.so.3

kcpp links OpenSSL 3. It is already present on most desktop installs, but a
minimal container image is usually missing it, and the failure is a loader
error before main() runs:

    kcpp: error while loading shared libraries: libssl.so.3: cannot open
    shared object file: No such file or directory

    Debian / Ubuntu     apt-get install -y libssl3
    Fedora / RHEL       dnf install -y openssl-libs
    Alpine              not supported - musl, not glibc

install.sh checks for it and says so before you hit that message.


INSTALL - WINDOWS
-----------------
    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.


INSTALL - LINUX
---------------
    tar xzf KCPP_ICPP_x64_2026-08-29.tar.gz
    cd KCPP_ICPP_x64_2026-08-29
    ./install.sh                    installs into ~/.local/kcpp
    ./install.sh /opt/kcpp          installs somewhere else (may need sudo)

install.sh prints the two lines to add to your shell profile; it does not edit
it for you, because a script that rewrites a login file without asking is how
people lose their shells.


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 forwards every argument to kcpp, so any kcpp flag works through it.

    python tools/icpplint.py yourscript.icpp     check the $var conventions


WHAT CHANGED SINCE 2026-08-09
-----------------------------
  * ICPP: a '$var' holding a string now owns its bytes. It used to store the
    right-hand side's pointer, so a value from a query or a concat silently
    became garbage when the next call reused that buffer.
  * ICPP: '$var' works as an unbraced for / while / do / if / else body, and
    inside switch arms. Those cases used to reach the code generator from the
    interpreter and crash.
  * ICPP: the ternary ?: read the condition's address instead of its value.
  * InternetSQL: LIKE '%term%' matches. The matcher could not step over the
    character a wildcard had matched, so only ONE literal could follow a '%':
    '%a%' worked and '%ab%' could never match, while '%aa%' matched any text
    holding a single 'a'. It also could not backtrack. Both the table scan and
    the index scan used it, so NOT LIKE was wrong in the mirrored way.
  * The version stamp is trustworthy: gen_version no longer counts the file it
    writes as an uncommitted change, so a clean tree finally reports clean.
  * icpp_strcmp no longer answers "equal" to a comparison it could not make.
    It requires both operands to be strings, and an unassigned $var is the
    number zero, so the old default of 0 meant

        if (icpp_strcmp($role, "admin") == 0) { ... }

    passed whenever $role was misspelled or unset. It now returns -1, which is
    non-zero, still negative for ordering, and still inside the documented
    -1/0/1 contract. icpp_version_cmp had the same defect. If you have an
    older build and a guard shaped like the line above, check it.
  * The parser no longer corrupts its own heap on a string literal longer than
    the token buffer; it reports the literal as too long instead.
