A small language compiler, written in Python and targeting LLVM.
Language guide · Architecture · Installation · Contributing · Roadmap
Kinetic is an early compiler prototype (1.3.0). It reads Kinetic source, performs lexical, syntactic, and type analysis, emits verified textual LLVM IR through llvmlite, and uses Clang to produce a native executable.
The long-term goal is a readable systems language. The current prototype is deliberately small; it does not yet provide a standard library or a production memory-safety model.
- Type inference and implicit function returns.
- Immutable bindings with opt-in mutation.
- Conditional branches and loops.
- Integer and string values, integer arrays, and array indexing.
- Indexed assignment through mutable array bindings, with the same guards as reads.
- Array element counts through the length builtin and runtime checks on indexed reads and writes.
- String length, byte reads, bytewise comparisons, slicing, and concatenation.
- A built-in printing operation for one integer or string at a time.
Start with the language guide and the programs in examples.
The introductory example is a complete Kinetic program:
func main() {
print("Hello World!")
}
Functions use func, immutable bindings use
let, and mutable bindings use
mut. See the syntax guide for
declarations, reassignment, and function calls.
You need Python 3.10 or newer, a compatible llvmlite release, and Clang on your executable search path. See installation for details.
Install the Python dependency:
python -m pip install -r requirements.txtCompile and run the introductory example:
python kinetic.py run examples/01_hello.knCompile without running the result:
python kinetic.py build examples/01_hello.knThe root launcher provides the build and run commands. Generated IR and native binaries are written next to the input source.
Compiler sources, documentation, examples, and development utilities each have one clear location.
| Area | Responsibility |
|---|---|
| Compiler | A flat Python package containing all compiler stages and the CLI. |
| Documentation | Language reference, architecture, and repository design. |
| Examples | Eleven numbered programs plus compile-time error, runtime-failure, and warning examples for 1.3.0. |
| Tools | Repository maintenance utilities, separate from the compiler CLI. |
| Tests | Separate layout, frontend, backend, and opt-in native suites. |
| Package configuration | Python packaging and the optional installed command. |
See the layout guide for the directory responsibilities.
Run the dependency-free, static-only repository checks:
python -B -m unittest discover -s tests -p test_layout.py -vThis checks syntax, layout, links, and keyword mapping without importing the compiler or generating IR. The general test runner also discovers behavioral tests: frontend tests run directly, backend tests generate IR when llvmlite is installed, and native tests require explicit opt-in plus Clang and llvmlite. Do not use that general runner for static-only work.
The GitHub Actions workflow runs on pushes, pull requests, and manual dispatches. Its Windows/Linux matrix runs the general runner on Python 3.10 and 3.14 without installing llvmlite. A separate Ubuntu Python 3.10 job installs the runtime dependency and runs frontend/backend tests. A third Ubuntu job enables native testing and uses the runner-provided Clang toolchain to build and execute all eleven numbered examples plus the runtime-failure programs. A passing native job verifies the covered end-to-end behavior for that revision; configuration alone is not evidence of success. See contributing.
Mutable integer-array bindings gain indexed assignment: values[i] = x writes
one element in place. The target must be declared with mut; immutable
bindings and parameters are rejected at compile time. Known constant
out-of-bounds writes are compile-time errors, and dynamic writes carry the same
runtime bounds guard as reads. Copies share element storage, so a write is
visible through every alias. The indexed-writes example
demonstrates in-place updates and alias visibility.
Strings gain source-text operations. len() reports a string's byte length,
indexing reads one byte with the same runtime range guard as arrays, ==/</>
compare bytewise, + concatenates into new storage, and the reserved slice()
builtin copies a checked start/end range into new NUL-terminated storage. The
text example demonstrates each operation. String result
storage is allocated at runtime and never reclaimed, matching the prototype's
array-storage simplification rather than a memory-safety model.
Array element storage now lives on the heap until process exit, so helpers can return locally created arrays without leaving their callers with stack-backed data. A failed allocation for a nonempty array traps before any elements are initialized. Empty arrays remain valid length-zero values.
This is a patch release for existing array behavior; source syntax is unchanged. Storage is never reclaimed, so repeated construction leaks memory. These fixes do not introduce garbage collection, ownership checking, or a production memory-safety model. The array-lifetime example demonstrates returned data surviving later calls. See array semantics for details.
The array-length example demonstrates
len(): an integer-array element count that travels
with the array through copies, reassignment, and function calls. The
byte-processing example now uses this builtin
instead of a manually synchronized length.
Every indexed read emits a negative/upper-bound check before computing the element address and loading it. A failed runtime check traps, and run mode returns failure. Runtime-failure examples are separate from compile-time diagnostic examples. These checks do not detect dangling array storage, make arrays resizable, or provide production memory safety.
This is an implementation change, not only a design update. Frontend, IR, native, and CLI regression tests cover it, and the hosted native CI job builds and runs the native suites on every push. The bootstrap interface itself remains a specification.
The current goal is to build the foundations needed for a compiler written in Kinetic that can compile itself. Version 1.3.0 is not self-hosting yet. The roadmap separates completed work, current planning, and future milestones.
See LICENSE.