ICPP library format

An ICPP library is just a .icpp file of reusable functions. There is no special packaging: you pull one into a script with the ordinary C include, which already works in -icpp mode.

#include "stringutil.icpp"

void main()
{
    iprint(su_shout("hi"));            // -> HI!
    iprint(su_wordcount("a b c"));     // -> 3
}

The manifest header

By convention every library begins with a manifest: a block of comment lines tagged @icpp-<field>. Because they are comments, the interpreter ignores them when running the library - but a script can read them (see below) to record provenance and check versions.

//@icpp-library    stringutil
//@icpp-version     1.2.0
//@icpp-author      Muhammad Anisur Rahman
//@icpp-copyright   (c) 2026 Muhammad Anisur Rahman - MIT
//@icpp-contact     [email protected]
//@icpp-requires    0.40                 ; minimum interpreter version
//@icpp-since       1.2.0: added su_repeat(); 1.1.0: added su_pad()   ; what's new

Rules:

One tag per line, //@icpp-<field> then the value.
A value runs to the end of the line, or to an inline ; comment, whichever comes first; surrounding whitespace is trimmed. So //@icpp-requires 0.40 ; min interpreter has the value 0.40.
The first occurrence of a tag wins. Put the manifest in the first ~200 lines (the reader stops scanning there).

Recommended fields

Field	Meaning
`library`	the library's name
`version`	its version, as dotted numbers (`MAJOR.MINOR.PATCH`)
`author`	who wrote it
`copyright`	copyright / license line
`contact`	email or URL
`requires`	minimum interpreter/API version it needs (backward compatibility)
`since`	what changed, newest first (what's new from the previous version)

Fields are free-form; add your own (@icpp-repo, @icpp-tags, ...) - the reader can fetch any of them.

Reading a manifest from a script

Three builtins let a script inspect a library file (its own or a dependency's):

icpp_lib_field(file, field)   // -> the @icpp-<field> value, or "" if absent
icpp_lib_version(file)        // -> shorthand for field "version"
icpp_version_cmp(a, b)        // -> -1 / 0 / 1, dotted-number SEMANTIC compare
                              //    (so "1.10.0" > "1.9.0", unlike a text compare)

Typical use - a backward-compatibility gate that refuses to run against a library that is too old:

#include "stringutil.icpp"

void main()
{
    if (icpp_version_cmp(icpp_lib_version("stringutil.icpp"), "1.2.0") < 0)
    {
        iprint("stringutil >= 1.2.0 required");
        icpp_exit(1);
    }
    iprint(su_repeat("ab", 3));        // -> ababab
}

stringutil.icpp in this directory is the reference example. The conformance suite exercises the same mechanism in test/icpp_conformance/07_library.icpp.