# langkit
[](https://crates.io/crates/langkit)
[](https://docs.rs/langkit)
[](https://github.com/livsy29/langkit/actions/workflows/ci.yml)
[](LICENSE)
Langkit is a Rust builder library for creating programming languages with a simple, high level API.
The goal is to let you build a usable language with minimal boilerplate while keeping control when
you need it.
## Status
Version 1.0.0 is released. The public API is stable and follows semver.
## Highlights
- Built in module packs via `lang.lib("base")` (math, io, fs, net, time, http).
- File imports with module namespacing (`import "utils.arc"` -> `utils.*`).
- Bytecode cache and fast rebuilds (`.lbc`).
- Minimal LSP diagnostics and a JSON-RPC LSP loop.
- Tiny macro helpers: `@include("file")`, `@repeat(n){...}`.
- REPL with history.
- Structs with methods and field access (`fn Type.method(self) { ... }`).
- Collections: map, set, tuple helpers.
## Install
```bash
cargo add langkit
```
For development from source:
```bash
git clone https://github.com/livsy29/langkit.git
cd langkit
cargo build
```
## MSRV
Minimum supported Rust version: **1.85.0** (edition 2024).
## Feature Flags
No optional feature flags are defined yet.
## Quick Start (with error handling)
```rust
use langkit::{Lang, Typing, Value};
fn main() {
let mut lang = Lang::new();
lang.name("arc");
lang.extension(".arc");
lang.var("let");
lang.mut_kw("var");
lang.assign("=");
lang.typing(Typing::Dynamic);
lang.mode(langkit::Mode::Compiler);
lang.lib("base");
lang.token("print");
lang.action("print", Box::new(|args| {
let s: Vec<String> = args.iter().map(|a| a.to_string()).collect();
println!("{}", s.join(" "));
Value::Null
}));
if let Err(e) = lang.run("let x = 5\nprint x") {
eprintln!("Error: {}", e);
}
}
```
## Configuration
You can configure behavior in code or via config:
```text
# langkit.toml
name = "arc"
extension = ".arc"
typing = "dynamic"
lib = "base"
build_dir = "build"
libs_dir = "libs"
safe = "safe"
```
Inline config (at the top of a source file):
```text
#langkit
name = "arc"
extension = ".arc"
lib = "base"
#end
```
## Examples
Examples and tests in the repo:
- [examples/](/examples)
- [tests/](/tests)
### Import
`main.arc`
```text
import "utils.arc"
print utils.add(2, 3)
```
`utils.arc`
```text
fn add(a, b) { return a + b }
```
### Struct + Method
```text
struct Person { name, age }
fn Person.greet(self) { print self.name }
let p = Person("Ann", 20)
p.greet()
```
### Map / Set / Tuple
```text
let m = map_new()
m = map_set(m, "name", "Ann")
print map_get(m, "name")
let s = set_new()
s = set_add(s, 1)
print set_has(s, 1)
let t = tuple(1, "x", 3)
print tuple_get(t, 1)
```
## Imports and Modules
- `import "file.arc"` loads the file and namespaces its symbols by file stem.
- Imported functions and structs are called as `module.symbol`.
- Search paths include the current file directory and `libs_dir` if set.
## Bytecode Cache
If a `.lbc` file is newer than the source, it is used automatically:
```text
main.arc -> main.lbc
```
You can also build explicitly:
```text
lang build main.arc
```
To build a native executable (AOT wrapper):
```text
lang build main.arc --exe
```
Size-optimized builds are used by default for `--exe` (LTO + strip + opt-level z).
## LSP
Minimal JSON diagnostics are supported:
```text
lang check main.arc --lsp
lang lsp
```
## REPL
```text
lang repl
```
## CLI (example)
```text
lang run main.arc
lang check main.arc
lang build main.arc
lang build main.arc --exe
lang test tests
lang repl
```
## Testing in the Language
Assertions exist as normal calls:
```text
assert(x > 0)
assert_eq(a, b)
assert_ne(a, b)
```
## Custom Modules
```rust
use langkit::{Lang, Module, Value};
let mut lang = Lang::new();
let mut m = Module::new("my");
FFI modules can be registered via `lang.ffi("mylib.dll")` and are exposed under a module name.
The library must export a `langkit_register` function that registers functions.
## Roadmap
Short 1.0.x focus areas live in [ROADMAP.md](/ROADMAP.md).
## Changelog
See [CHANGELOG.md](/CHANGELOG.md).
## Release Process
Recommended flow for releases:
1. Follow semver for versioning.
2. Update `Cargo.toml` version.
3. `git commit` the changes.
4. `git tag vX.Y.Z`
5. `git push --tags`
6. `cargo publish`
## CI Recommendation
Use GitHub Actions to run tests on each push and publish on tags.
See `.github/workflows/ci.yml` as a baseline and add a publish workflow if needed.
## Contributing
Please read [CONTRIBUTING.md](/CONTRIBUTING.md) before opening PRs.
## Code of Conduct
See [CODE_OF_CONDUCT.md](/CODE_OF_CONDUCT.md).
## License
MIT, see [LICENSE](/LICENSE).