Karina Compiler

karina-lang.org

Karina is a statically typed, general-purpose, high-level programming language that emphasizes simplicity, interoperability, and concise notation. Karina is fully compatible with Java, allowing you to use existing libraries and frameworks seamlessly while enjoying a modern programming experience.

Tip

Install the Karina VSCode Extension

If you run into any issues, bugs, unexpected behavior, or have any questions while using this project, you’re encouraged to open an issue.

Outline

• Documentation and Features
• Installer and CLI
• Local development
• Compiler architecture
• Licenses

Documentation

The official documentation is available at karina-lang.org.

Installer and CLI

You need Java 23 or higher. You can use SDKMAN! to manage your Java versions.

To install the Karina compiler, download and run the installer. After the installation, you can run the compiler from the command line:

karina -v

Karina: v0.7
Java: OpenJDK 64-Bit Server VM 23.0.2

Hello World

karina new hello-world
cd hello-world
karina run

Hello, World!

Local development

• Demo Karina Project
• Compiler Code
• Standard Library Code
• LSP Code

You need Java 23 or higher. You can use SDKMAN! to manage your Java versions.

 git clone https://github.com/Plixo2/KarinaC.git
 cd KarinaC

The compiler is a standard Gradle project, so you can use it with any IDE that supports Gradle.

You can run the compiler via the Gradle task compiler:run:

 gradlew compiler:run

The project is configured to build the demo project in resources/src/ by default.

Note

This project consists of multiple Gradle subprojects. Make sure to run the Gradle jar task's when updating the standard library or the compiler.

Custom Environment

You can set System environment flags via build.gradle or the vm arguments in your IDE.

application {
  // ...
  applicationDefaultJvmArgs = ['-Dkarina.source="resources/local/"'] // set the source folder to your local dev folder
}

Flags:

karina.source

karina.source="<src folder>"

Points to your local development folder. Defaults to resources/src/

karina.out

karina.out="<build file>"

Specifies the output JAR file. Defaults to resources/out/build.jar

karina.classes

karina.classes="<true/false>"

Enables/Disables the generation of .class files. Defaults to true

karina.flight

karina.flight="<debug file>"

Specifies the debug flight recorder file path. Defaults to resources/flight.txt

karina.console

karina.console="<true/false>"

Enables/Disables the flight recorder output to the console. Defaults to true

karina.binary

karina.binary="<true/false>"

Enables/Disables the usage of a binary format for faster reading of precompiled classes. Can improve startup performance by over 20 times, but untested and may cause issues. Defaults to false

karina.logging

karina.logging="<none/basic/verbose/verbose_jvm>"

Enables/Disables the flight recorder output to the console. Defaults to none. Useful for debugging the compiler.

Customize Logging

You can set custom log types in here.

Adding log types will enable logging for specific parts of the compiler. You can gain detailed insights into the inner workings of the compiler by setting the correct logging types.

E.g. LogTypes.CHECK_TYPE will get you a very detailed view of the type checking process.

Note

This is the primary way to debug the compiler. Be aware that this will generate a lot of output, when too many log types are enabled.

javap

Another helpful tool is javap. Use it to inspect the generated bytecode in detail.

javap -c -v -p main.class > main.txt

This will write the bytecode of the main.class file to main.txt, where it can be inspected.

Rebuild the standard library

You can rebuild the standard library with the Gradle task stdlib:buildForCompiler:

gradlew stdlib:buildForCompiler

This will create a new karina.base.jar file, located in src/main/resources

After that run the task compiler:buildCache:

gradlew compiler:buildCache

This will rebuild the cache for the compiler, so it can use the new standard library.

Compiler architecture

Internals

• Read the source code into memory
• Load the precompiled JAR files (java.core and the karina.base) into a ClassModel
• Parser Stage
  • Parse the loaded files into tokens, then into an AST via Antlr
  • Convert the Antlr AST into a ClassModel and IR
• Import Stage
  • Resolve all types via imports
• Attribution Stage
  • Expression validation and type inference
• Lower Stage
  • Construct new classes, bridge methods, rewrite loops, etc
• Generate Stage
  • Generate bytecode
• And then finally write the bytecode to disk

Important classes:

• Main Class
• Compiler Class
• KExpr Class
• KType Class

Important Packages

• jvm_loading
  • Responsible for loading precompiled classes
• model_api
  • The API for the ClassModel. Represents all loaded classes and their fields, methods, etc
• stages
  • All stages of the compiler.

Licenses

Karina is published under two licenses:

• Apache License 2.0
• MIT License

SPDX-License-Identifier: Apache-2.0 or MIT

You may use this software under the terms of any license you choose.