Skip to content

Kairo 0.2.3

Latest

Choose a tag to compare

@Ze7111 Ze7111 released this 13 Nov 04:44
· 2 commits to main since this release
Immutable release. Only release title and notes can be modified.
4297ec7

Warning

This is an alpha. The syntax, command-line flags and standard library can still change before 1.0.

0.2.3 follows 0.2.1 (there is no 0.2.2). It adds kals, a language server with clients for VS Code, Zed and Neovim, makes C++ libraries much more usable from Kairo, tightens a long list of language rules that used to slip through to the C++ compiler, and lays the groundwork for incremental compilation.


What's new

kals, the language server

kals ships in the toolchain beside kairo, kcc and kfmt. The editor clients live in kairo-lsp: the VS Code extension 0.9.2, the Zed extension 0.3.0 and a Neovim plugin, configured the same way.

  • Projects. kairo_compile.json names the entry points and their flags. python3 build.py --emit-compile-json writes one for the compiler's own tree. Editing it republishes the open files' diagnostics.
  • Live check, on by default. Each project keeps its import graph checked in a worker process and re-checks an edit in place: the edited file first, the files that import it in the background. On the compiler's own 426 files that is about 130 ms to the edited file's results, against 8.5 s for a full check (release build). Set liveCheck: false, or KALS_LIVE_CHECK=0, for one compiler process per analysis.
  • Typing a half-finished line costs little. A syntax-only pass answers a keystroke first (about 30 ms on a 3,000-line file). Broken text is checked in a throwaway copy of the worker, in a quarter to half a second on an ordinary file. Saving, or opening or closing an unchanged file, starts no analysis; an edit made during a slow analysis replaces it; requests are cancellable; progress shows as "Indexing Kairo N/M".
  • A file that does not parse keeps working. Errors inside function bodies leave the file indexed, the rest of the project keeps its results, and hover, jumps, references, inlay hints, code lenses and colours keep answering on the lines you did not touch.
  • Completion from the index, in a few milliseconds and while the code does not parse: names in scope, members after . -> :: (respecting pub / prot / priv, and extension members only where their file is imported), primitives' constants and extension statics (usize::, f64::), keywords that fit the position, attributes after @, macros, import paths, header paths in ffi import "...", members of C and C++ types, and names inside f-string {}. It also completes after a[i]., f()[k]., (expr)., self[i]., (*p). and x?.. Option indexCompletion, on by default.
  • Navigation: go to definition, type definition and implementation; references; call and type hierarchy; document and workspace symbols; document links. Loop variables and pattern bindings have hover, references and highlighting.
  • Hover shows the full declaration: a class with its methods, extension methods, attributes, modifiers, generic parameters, derives and impl, and its size and alignment (also for enums, C++ types and classes with bases or virtual methods); an enum with its underlying type and every variant; C++ reference parameters as @inout / @move and reference returns as ffi::ref<T>; a macro call with its expansion.
  • Edits: diagnostics with fix-its, formatting through kfmt (document, range and on-type), rename (a class rename renames its constructors), folding and selection ranges, signature help, inlay hints for parameter names, inferred types and interface members, and code lenses.
  • Code actions: apply a fix-it, view or inline a macro expansion, generate an interface from a class's public methods.
  • Semantic highlighting, one meaning per style: underline for overloaded calls, underline and italic for dispatched (where / requires) calls, italic for extension and C/C++ calls, bold for unsafe code, strikethrough for deprecated uses. The & of a call argument is coloured by its parameter: @inout green, *T the theme's operator colour, unsafe *T purple, *const T grey-blue, unsafe *const T purple italic (also for &a.b, &v[i], named arguments, constructors and C++ T& / T* / const T* parameters). A macro name and its ! are one amber token, also while the file does not parse.
  • C and C++ files that #include "foo.k" get generated headers and a clang VFS overlay for clangd, including files outside compile_commands.json; a jump from C++ lands on the declaration in the .k file, doc comments reach the headers, and two servers on one root keep separate overlays.

C and C++ interop

  • C++ implicit conversions at C++ calls, opt-in. With -fcxx-implicit-conv, a value crossing into C++ may take one C++ user-defined conversion, as C++ ranks it, at a call, an initialisation, an assignment or a return (var s: cxx::std::string = "abc"). Without the flag, the error names the conversion C++ would use and offers an as T fix-it. fmt, spdlog and toml++ build and run this way.
  • Language flags apply to your code only. -fno-implicit-conv, -fcxx-implicit-conv and -funwind no longer change how Lib/builtin and Lib/std compile, so they no longer print the library's own errors before yours.
  • ffi "C" in any letter case is C, to every part of the compiler: ffi "C" import links (it used to mangle the names), and --no-cxx refuses every spelling of C++. The language string and what it applies to must be on one line.
  • An ffi import takes one header. A brace list or a lone ffi line is an error instead of a half-done import. A header with #include "file.k" gets one error at that line (R070) and the rest of the header still imports; ffi import "x.k" says to use import.
  • Kairo can define and override C++ functions that return references: ffi::ref<T>, ffi::ref<const T> and ffi::mref<T> as the return type, with return x.
  • Out-of-line definitions of members of C++ classes and of functions in C++ namespaces are emitted and callable from C++ (they were a link error).
  • C++ types: one identity per C++ type (nlohmann::json reached through different aliases is one type); literals rank and deduce as in C++ at C++ callees; auto return types of non-template imported functions are deduced; string literal suffixes call their C++ operator""; a header name equal to a builtin's (zlib's Byte) is an error only where the bare name is used; cxx::std::tuple<A, B> can be named.
  • Move-only Kairo classes inside C++ wrappers move. std::optional, std::tuple, std::variant, std::expected and std::pair of such a class are move-only.
  • kcc: answers the compiler probes build systems use (-dumpversion, -dumpmachine, -print-target-triple, -print-resource-dir, -print-search-dirs, -print-prog-name=, -print-file-name=, --print-libgcc-file-name); no longer links the Kairo runtime into pure C/C++ programs; can return a Kairo string or another module's record to C++; reports a bounded Kairo class template made with a non-conforming type by naming the bound.
  • Clearer interop errors: "no member named X" names the receiver's real C++ type and every such error in a file is reported; a write to a by-value C++ operator[] result is "not assignable"; an override whose return type differs from the C++ virtual's is SC294E with the C++ type as a fix-it; a capturing closure passed as a C function pointer says why it fails; unresolved names in a file whose C++ headers failed say why.
  • Smaller fixes: a by-value for over a C++ range of an abstract type is a Kairo error with a fix-it to for *x; range-for over an imported C++ template instance works inside a generic; a comparison of C++ iterators no longer depends on the order files are checked; a fn value made from a throwing C++ function no longer claims noexcept; a as A on a C++ record value and &null for a C function-pointer parameter compile.

Generics and interfaces

  • Primitive types meet interface bounds made of operators. T impl Add and T impl Ord accept i32, f64 and the other primitives through their built-in operators, from Kairo and from C++ hosts using kcc. Float % and <=> are not built-in operators, so floats do not meet bounds that need them.
  • A partial specialization can match a qualified argument: class <T> V<const T> is chosen for V<const i32> with T = i32, and is more specialized than V<T>.
  • A member's requires P impl I gives the member's body that bound; the member exists only on instances that meet it, and the bound is checked at subscripts and on @copy.
  • Static calls on container types: [i32]::with_capacity(8), {T}::f(), {K: V}::f().
  • Bounds are enforced where they used to be dropped: inside module blocks, on a bounded generic function used as a value, kind bounds (<T: class>, SC292E), and a copy bound on a container whose elements cannot be copied ([MoveOnly], SC162E).
  • Fixed arrays work in generics as a const or @inout generic parameter, as the receiver of an interface method or operator, and with extend [i32; 2] impl I. Passing an array by value to a generic parameter is an error (SC045E), and so is calling a generic that copies its T with a fixed array (SC083E).
  • Default arguments work on members of a generic extension, and a bound may be a rooted path (fn <T impl ::m::I>).

Language

  • A const container's elements are const. cb[0] = 5, cb[0] += 1, &cb[0] passed to @inout, and a mutating method on cb[0] are errors when cb is const; on a const object only the const self form of op [] is called; for *e in v over a const vector cannot write the elements. [T;] and [T] convert implicitly to [const T;].
  • op []=: a subscript can have a read form and a place form. op [] gives the element to read; op []= gives the place a write goes through. Writes, ++, @inout arguments and mutating method calls use op []=, everything else op []. A type without op []= behaves as before, and C++ callers still write b[i]. op -> may declare a self / const self pair.
  • const self means const. Writing a field of self that is not mutable var is an error (SC071E). A generator can yield a field, an element or a tuple from a const self method, and for *x over a generator that yields no mutable place binds a pointer to const.
  • Copies of move-only values are reported by Kairo (SC182E): the derived + on a variable, a field of a const parameter, an element of a C++ vector, a plain for binder, a container literal of move-only elements. **p = X() and v[f()] = X() with a move-only type compile.
  • Extensions follow your imports. A file sees an extend block's members only through the imports it writes and pub re-exports (prot inside the module). A member found only in an extension you have not imported is an error that names the file and offers the import.
  • extend covers more types, with clear errors for the rest. extend i32? and extend <T> [T]? work (self is the nullable), extend [i32; 2] methods work, and a static added to a primitive is called as i32::make(). Extending a pointer (SC282E), a function type (SC283E) or a bare type parameter (SC284E) is an error.
  • Strings. Adjacent literals join whatever their prefixes ("a" f"b {x}" r"\c" is one string). A literal suffix belongs to the whole joined string ("12" "3"_km is "123"_km); joined strings with a suffix warn (SC276W), two different suffixes are an error (SC277E). stringify! keeps r and f prefixes.
  • Macros. A macro can be imported by name (import lib::mac!, import lib::{mac!, f}). Operators and methods declared through a macro work. Errors in declarations a macro makes point at the invocation, with a note into the macro body. label! and jump! inside a macro body match each other.
  • Numbers. f8e4m3 and f8e5m2 are usable (literals, arithmetic, comparisons, conversions, printing). <=> on integers, characters and booleans yields a usable Ordering. Integer literals wider than 128 bits are range-checked against u256 / i256, and range errors quote the literal as written. Wide floats (f128, f256, f512) and primitive limits are fixed.
  • prot import no longer re-exports outside the module.
  • New checks, reported by Kairo instead of the C++ compiler: a constant index past a fixed array's end (SC291E), inline "asm" outside unsafe (SC296E, with a fix-it), a mismatched override return on a Kairo class (SC297E), eval fn op finally (SC290E), a brace initializer of a record whose only constructor is @copy or @move (SC088E), a write to a field of a temporary, a type name used as a value, abstract classes held by value, and never-defined records taken by value.
  • New warnings: a write to the copy bound by for x in v that is never read (SC275W, fix-it inserts *); a mixin hook that does not replace the base's because its parameter type differs (SC278W).
  • Fixes: a slice literal initialising a file-scope, module or script variable; a static local slice literal (it read freed memory); return in a fn main() with no result type; a panicking @no_inline function; an if-expression arm that calls a -> ! function; generic enum payloads (Opt<i64>::Some { v: 7 }), unwrap! and checked enum casts in global initializers, and v as E?; fields from a class eval if laid out in source order; a class holding a vector of itself keeps its copy constructor; non-ASCII identifiers across files; methods named test; files named like primitive types (f8.k); ADT variants named Tag; try ... catch => break without a false "loop never exits" warning; ffi "c" { fn ... } blocks; create<T>(args) checked against T's constructors.
  • Scripts: closures copy the top-level variables they capture; |*| captures them by pointer, and a |*| nested in a copying closure modifies that closure's copy.

Diagnostics and robustness

  • One error for a half-typed line. var x = 1 + before a closing } is one error at the right place. Empty slots ([1, , 3], f(1, , 2), Point { x: }) are reported as a missing expression. A top-level item the parser cannot read is reported and parsing continues (it used to stop reading the file silently). A field with no type is S058E.
  • Underlines sit under the right code: note ranges, labels in other files, carets after non-ASCII text, tabs and fix-it markers.
  • Diagnostics come out in the same order on every run, whatever the thread count.
  • One undeclared name no longer stops type checking for the rest of the file.
  • No more crashes on deep input: a chain of 30,000 terms compiles, and 1,500 chained operators type-check.
  • An intermittent crash on very large programs (a data race reading C++ declarations) is fixed.
  • spawn / thread expressions and calls through an interface pointer report "not yet supported" instead of crashing.
  • --explain and internal errors no longer print internal tracking numbers.

Build and tooling

  • Semantic analysis is about 9% cheaper on a large program, with identical output.
  • --incremental-sema (experimental, off by default): when nothing a build read has changed, the compiler skips parsing and semantic analysis and goes straight to the link. A no-change build of the compiler itself drops from about 51 s to about 5 s. --incr-verify checks a would-be hit against a full run. Changing HOME, XDG_CACHE_HOME or LOCALAPPDATA invalidates the cached results.
  • Groundwork for reuse after an edit: binary AST serialization (--emit-ast-bin) and incremental facts (--dump-interface, --dump-deps).
  • Caches are capped at 2 GB each (objects, runtime, library); the oldest entries go first, never one the current build uses.
  • --march with an unknown x86 CPU is a clear error (P006E); --mcpu native is accepted; --print-ast=tree shows struct and union constructors and operators; generated headers from --emit-headers compile on their own.
  • build.py: the LLVM prebuild is skipped when nothing changed, and concurrent builds no longer lose a shared object.

Upgrade notes

Code that 0.2.1 accepted may now be an error:

  • Extensions: a file that calls an extension method without importing the file that declares the extend block needs the import. The error names the file and offers it.
  • Const: writing an element of a const container, or a non-mutable field of self in a const self method, is an error.
  • Strings: a prefixed literal directly after another literal (f"a" f"b") is an error with a + fix-it; it used to drop the second literal.
  • ffi: the language string and what it applies to must be on one line, and ffi import takes one header.
  • Generics: passing a fixed array by value to a generic parameter is an error.
  • Modules: a name brought in by prot import is no longer visible outside the module.
  • for x in v binds a copy; write for *x in v to modify elements (SC275W points at the lost write).
  • A type name used as a value (x == u32) and extending a pointer type are errors.

Install

Quick install

Linux, macOS, FreeBSD and NetBSD (any shell):

curl -fsSL https://kairolang.org/install.sh | sh

Windows (PowerShell 5.1 or 7):

irm https://kairolang.org/install.ps1 | iex

Both are the same script, also attached below as install.sh and install.ps1. It detects your OS and CPU, downloads the matching archive and SHA256SUMS, verifies the checksum before unpacking, and never needs root or administrator rights. On Linux, macOS and the BSDs it installs to ~/.local/share/kairo/0.2.3 and links the tools into ~/.local/bin. On Windows it installs to %LOCALAPPDATA%\Kairo\0.2.3 and adds its bin to your user Path. Set KAIRO_PREFIX to install elsewhere, or KAIRO_TRIPLE to pick a different archive.

Editor support

Install kals with the toolchain (it is in bin/), then the client for your editor from kairo-lsp: the VS Code extension, the Zed extension, or the Neovim plugin. Each finds kals on your PATH.

Downloads

Linux (the compiler is statically linked against musl and runs on any distribution)

Architecture Archive
x86_64 kairo-0.2.3-x86_64-linux-musl.tar.xz
aarch64 kairo-0.2.3-aarch64-linux-musl.tar.xz
armv7 kairo-0.2.3-armv7-linux-musl.tar.xz
i686 kairo-0.2.3-i686-linux-musl.tar.xz
riscv64 kairo-0.2.3-riscv64-linux-musl.tar.xz

Windows (MinGW builds; no extra runtime needed)

Architecture Archive
x86_64 kairo-0.2.3-x86_64-windows-gnu.zip
aarch64 kairo-0.2.3-aarch64-windows-gnu.zip
armv7 kairo-0.2.3-armv7-windows-gnu.zip
i686 kairo-0.2.3-i686-windows-gnu.zip

macOS

Architecture Archive
Apple Silicon (arm64), macOS 11.0+ kairo-0.2.3-arm64-apple-macosx11.0.zip
Intel (x86_64), macOS 10.15+ kairo-0.2.3-x86_64-apple-macosx10.15.zip

BSD

Platform Archive
FreeBSD x86_64 kairo-0.2.3-x86_64-unknown-freebsd.tar.xz
FreeBSD aarch64 kairo-0.2.3-aarch64-unknown-freebsd.tar.xz
NetBSD x86_64 kairo-0.2.3-x86_64-unknown-netbsd.tar.xz

The i686 builds need an SSE2-class CPU (Pentium 4 or newer), and the ARM builds need ARMv7 or newer.

To install by hand, download an archive and SHA256SUMS, verify it, unpack it anywhere and add its bin folder to your PATH:

sha256sum -c --ignore-missing SHA256SUMS
tar -xJf kairo-0.2.3-x86_64-linux-musl.tar.xz
export PATH="$PWD/kairo-0.2.3-x86_64-linux-musl/bin:$PATH"

Keep the folder layout as it is: the tools find their libraries, runtime and sysroots relative to bin.

Archives downloaded with a browser may be blocked on first run on macOS and Windows; see Troubleshooting.

SHA-256 checksums

The same values as the attached SHA256SUMS (which covers the archives; the installers are listed here too). On macOS use shasum -a 256 <file>; on Windows, Get-FileHash -Algorithm SHA256 <file>.


Targets

Unchanged from 0.2.1. Pass --target; ksys builds the sysroot the first time. ksys probe <target> shows how Kairo reads a target name.

OS / libc Architectures
Linux, musl (static) x86_64, x32, i686, aarch64, aarch64_be, armv6, armv7, thumbv7, riscv64, riscv32, powerpc, powerpc64, powerpc64le, s390x, mips, mipsel, mips64, mips64el, loongarch64
Linux, glibc 2.17–2.42 (riscv32 from 2.33, loongarch64 from 2.36) x86_64, i686, aarch64, aarch64_be, armv7, riscv64, riscv32, powerpc, powerpc64, powerpc64le, s390x, mips, mipsel, mips64, mips64el, loongarch64
Windows, MinGW (UCRT) x86_64, i686, aarch64, armv7
Windows, MSVC (SDK via scripts/msvc-sysroot) x86_64, i686, aarch64
macOS (your SDK) arm64, x86_64
FreeBSD 14.4 x86_64, aarch64
NetBSD 10.1 x86_64
WASI wasm32

Linux programs build against glibc 2.31 by default, so they run on any distribution with glibc 2.31 or newer.


Known limitations

  • Language server: without live check, every edit re-checks the whole import graph of its entry point (about 10 s on a 420-file project). Live check's memory is bounded only by restarting its worker. Zed does not request inlay hints. The generated headers for clangd do not yet parse under a stock clangd in files that pull in the Kairo runtime.
  • kld does not compare C++ ABI flags across objects. Mixing objects built with different -fshort-enums, -frtti or similar flags links without a warning (or fails with an ordinary undefined symbol); build every C++ object of a program with the same flags.
  • Float % and <=> are accepted by the type checker and rejected by the C++ backend.
  • --incremental-sema reuses nothing after an edit yet; any change is a full build.
  • Everything in 0.2.1's known limitations still applies; the current list is on the Implementation Status page.

Troubleshooting

macOS: "cannot verify this app is free of malware" when running a downloaded release binary. Release binaries aren't notarized yet. If you downloaded the archive with a browser, clear the quarantine flag on the unpacked folder (the curl installer doesn't need this):

xattr -dr com.apple.quarantine ./kairo-0.2.3-arm64-apple-macosx11.0

Windows: Defender or SmartScreen flags the downloaded binary. Release binaries aren't code-signed yet, so SmartScreen shows "Windows protected your PC" on first run. Click More info -> Run anyway. If Defender quarantines the archive outright, unblock it before extracting:

Unblock-File -Path .\kairo-0.2.3-x86_64-windows-gnu.zip

The PowerShell installer (irm https://kairolang.org/install.ps1 | iex) downloads without the browser's mark of the web, so it usually avoids both prompts.

kairo: command not found after installing. The installer links the tools into ~/.local/bin (on Windows it adds the install's bin folder to your user PATH). Open a new terminal, or add ~/.local/bin to PATH if your shell doesn't include it.

The editor says it cannot start kals. The client looks for kals on PATH; open the editor from a shell where kals --version works, or set the client's server path option to the bin/kals of your install.

error [P008E] or [P009E] for a *-apple-macosx or *-windows-msvc target. Apple's and Microsoft's SDKs can't be redistributed. On a Mac, Kairo builds the macOS sysroot from your installed SDK automatically (install the Command Line Tools with xcode-select --install if it says none was found); from another host, run scripts/darwin-sysroot.sh against a copy of the SDK. For MSVC, run scripts/msvc-sysroot.sh (or msvc-sysroot.ps1 on Windows), which downloads the MSVC runtime and Windows SDK from Microsoft after asking you to accept its license.

error [P009E] when using --target. ksys refused to build a sysroot for that target. The message says why: --no-sysroot-build is set, the target isn't one Kairo supports yet, or the glibc version is out of range. ksys probe <target> shows what Kairo understood the target to be.

error [P010E] when using --target. Building the sysroot failed. The message names the stage that failed and its log directory, and the next build retries that stage. Please file an issue with the log.


Feedback

This is what an alpha is for. Please file issues using the templates. If the compiler reports an internal error, paste the full output and the smallest file that reproduces it.

Report security issues privately, as described in SECURITY.md: through GitHub's private vulnerability reporting, or by email to security@kairolang.org.


License

Kairo is licensed under Apache-2.0 WITH AdditionRef-Kairo-Runtime-exception.

  • Programs you compile with Kairo, and the code the compiler generates into them, are yours to license under any terms.