Development Setup

Prerequisites

Before you begin, ensure you have the following installed:

Required Tools

JDK

Java Development Kit 11 or higher

Kotlin

Kotlin 2.3.0 (managed by Gradle)

Gradle

Included via Gradle Wrapper

Git

For cloning the repository

System Requirements

OS: Linux (any distribution)
Hardware: Lenovo laptop with ACPI support
Kernel Module: acpi_call loaded (lsmod | grep acpi_call)
Memory: At least 3GB RAM for Gradle builds

KVantage is designed specifically for Lenovo laptops. Running on other hardware may cause undefined behavior.

Getting Started

Clone the repository

git clone https://github.com/kosail/KVantage.git
cd KVantage

Verify Gradle setup

The project uses the Gradle Wrapper, so no separate Gradle installation is needed:

./gradlew --version

This will automatically download Gradle if needed.

Build the project

Build the entire project with:

./gradlew build

This compiles the Kotlin code, processes resources, and runs tests.

Run the application

Launch KVantage in development mode:

./gradlew run

The application will prompt for your sudo password to start the backend daemon with root privileges.

Compose Multiplatform Setup

KVantage is built with Compose Multiplatform for Desktop version 1.10.0.

Key Technologies

Technology	Version	Purpose
Kotlin	2.3.0	Primary language
Compose Multiplatform	1.10.0	UI framework
Material 3	1.10.0-alpha05	Design system
Compose Hot Reload	1.0.0	Fast development iterations
Kotlinx Serialization	1.10.0	JSON/data handling
Lifecycle ViewModel	2.9.6	State management

Project Configuration

The project uses Gradle’s version catalog (gradle/libs.versions.toml) to manage dependencies consistently.

View build.gradle.kts structure

plugins {
    alias(libs.plugins.kotlinMultiplatform)
    alias(libs.plugins.composeMultiplatform)
    alias(libs.plugins.composeCompiler)
    alias(libs.plugins.composeHotReload)
    alias(libs.plugins.kotlinxSerialization)
}

kotlin {
    jvm()
    
    sourceSets {
        commonMain.dependencies {
            // Compose runtime and UI
            implementation(libs.compose.runtime)
            implementation(libs.compose.foundation)
            implementation(libs.compose.material3)
            implementation(libs.compose.ui)
            implementation(libs.compose.components.resources)
            implementation(libs.compose.uiToolingPreview)
            
            // Lifecycle and state management
            implementation(libs.androidx.lifecycle.viewmodelCompose)
            implementation(libs.androidx.lifecycle.runtimeCompose)
            
            // Serialization
            implementation(libs.kotlinx.json.serializer)
        }
        
        jvmMain.dependencies {
            implementation(compose.desktop.currentOs)
            implementation(libs.kotlinx.coroutinesSwing)
        }
    }
}

Development Workflow

Hot Reload

The project includes Compose Hot Reload for faster development:

./gradlew run --continuous

This watches for file changes and automatically recompiles.

Building a Distribution

Create a distributable JAR:

./gradlew packageDistributionForCurrentOS

Or build for release:

./gradlew packageReleaseDistributionForCurrentOS

The output will be in composeApp/build/compose/binaries/main/.

Gradle Configuration

The project is configured with:

# kotlin.code.style=official
# kotlin.daemon.jvmargs=-Xmx3072M
# org.gradle.jvmargs=-Xmx3072M
# org.gradle.configuration-cache=true
# org.gradle.caching=true

These settings optimize build performance and enable Gradle caching.

Project Structure

KVantage/
├── composeApp/                 # Main application module
│   ├── src/
│   │   └── jvmMain/
│   │       ├── kotlin/         # Kotlin source code
│   │       │   └── com/korealm/kvantage/
│   │       │       ├── models/      # Data models
│   │       │       ├── state/       # State management
│   │       │       ├── ui/          # UI components
│   │       │       │   └── mainUI/  # Main screens
│   │       │       └── Main.kt      # Entry point
│   │       └── composeResources/    # Resources and i18n
│   │           ├── drawable/        # Images and icons
│   │           ├── values/          # English strings
│   │           ├── values-es/       # Spanish
│   │           ├── values-ja/       # Japanese
│   │           ├── values-de/       # German
│   │           ├── values-fr/       # French
│   │           ├── values-pt/       # Portuguese
│   │           ├── values-kr/       # Korean
│   │           └── values-zh/       # Chinese
│   ├── bin/                    # Backend daemon binary
│   └── build.gradle.kts        # App build configuration
├── gradle/                     # Gradle wrapper and config
│   └── libs.versions.toml      # Version catalog
├── build.gradle.kts            # Root build configuration
├── settings.gradle.kts         # Project settings
└── gradlew                     # Gradle wrapper script

Entry Point

The application entry point is composeApp/src/jvmMain/kotlin/com/korealm/kvantage/Main.kt:

package com.korealm.kvantage

fun main() {
    // Application initialization
}

Main class configuration in build.gradle.kts:

compose.desktop {
    application {
        mainClass = "com.korealm.kvantage.MainKt"
    }
}

Debugging Considerations

NEVER test as root! The GUI should always run as a normal user.

Debug Mode

Run with debug output:

./gradlew run --debug

Or attach a debugger to the Gradle process:

./gradlew run --debug-jvm

Then attach your IDE debugger to port 5005.

Common Issues

Backend daemon not starting

Ensure the kvand binary in composeApp/bin/ is executable:

chmod +x composeApp/bin/kvand

Verify the ACPI module is loaded:

sudo modprobe acpi_call
lsmod | grep acpi_call

Out of memory during build

Increase Gradle memory in gradle.properties:

org.gradle.jvmargs=-Xmx4096M

Compose UI not rendering

Ensure you have proper graphics drivers and X11/Wayland support.Check Java version:

java -version

Requires JDK 11 or higher.

Permission denied errors

The app needs root access for ACPI operations. Ensure:

Your user is in the sudo group
You can execute sudo commands
The backend daemon requests permissions properly

Logging

Use proper logging! The project maintainer emphasizes this after debugging challenges with root-level operations.

When debugging:

Add logging to track execution flow
Log ACPI interactions and responses
Include error context and stack traces
Use appropriate log levels (DEBUG, INFO, WARN, ERROR)

Backend Daemon Development

The backend daemon (kvand) is developed separately:

Repository: github.com/kosail/Kvand
Language: Go (Golang)
Location: Pre-compiled binary in composeApp/bin/kvand

Why Go?

The daemon was reimplemented in Go due to:

JVM limitations for low-level system operations
Kotlin Native constraints with ACPI access
Better performance for system daemon operations
Static binary distribution (no runtime dependencies)

Backend Communication

The GUI communicates with the daemon via:

Local socket or IPC mechanism
JSON messages (using kotlinx-serialization)
Root isolation - only daemon runs with privileges

For backend modifications, clone the Kvand repository separately and rebuild the binary.

IDE Setup

IntelliJ IDEA (Recommended)

Open the project in IntelliJ IDEA
IDEA will auto-detect the Gradle configuration
Wait for Gradle sync to complete
Run configurations will be automatically created

VS Code

Install the Kotlin extension
Install the Gradle extension
Open the project folder
Use terminal for Gradle commands

Next Steps

Now that your environment is set up:

Read the Contributing Guidelines for code standards
Explore the Architecture to understand the codebase
Check open issues for tasks to work on
Join discussions on GitHub for questions

Ready to contribute?

Review our contributing guidelines to get started with your first PR

Overview

Getting Started

Core Features

Architecture

Troubleshooting

Contributing

Development Setup

Prerequisites

Required Tools

JDK

Kotlin

Gradle

Git

System Requirements

Getting Started

Compose Multiplatform Setup

Key Technologies

Project Configuration

Development Workflow

Hot Reload

Building a Distribution

Gradle Configuration

Project Structure

Entry Point

Debugging Considerations

Debug Mode

Common Issues

Logging

Backend Daemon Development

Why Go?

Backend Communication

IDE Setup

IntelliJ IDEA (Recommended)

VS Code

Next Steps

Ready to contribute?

Build docs developers (and LLMs) love

Overview

Getting Started

Core Features

Architecture

Troubleshooting

Contributing

​Prerequisites

​Required Tools

JDK

Kotlin

Gradle

Git

​System Requirements

​Getting Started

​Compose Multiplatform Setup

​Key Technologies

​Project Configuration

​Development Workflow

​Hot Reload

​Building a Distribution

​Gradle Configuration

​Project Structure

​Entry Point

​Debugging Considerations

​Debug Mode

​Common Issues

​Logging

​Backend Daemon Development

​Why Go?

​Backend Communication

​IDE Setup

​IntelliJ IDEA (Recommended)

​VS Code

​Next Steps

Ready to contribute?

Build docs developers (and LLMs) love

Prerequisites

Required Tools

System Requirements

Getting Started

Compose Multiplatform Setup

Key Technologies

Project Configuration

Development Workflow

Hot Reload

Building a Distribution

Gradle Configuration

Project Structure

Entry Point

Debugging Considerations

Debug Mode

Common Issues

Logging

Backend Daemon Development

Why Go?

Backend Communication

IDE Setup

IntelliJ IDEA (Recommended)

VS Code

Next Steps