Usage & Installation¶

ktox-cpp is distributed as a Gradle plugin. This guide will help you set it up in your Kotlin project.

Installation¶

Add the following to your build.gradle.kts file:

1. Apply the Plugin¶

plugins {
    id("com.isycat.ktox.cpp") version "1.0.0"
}

2. Configure the Transpiler¶

Use the kotlinToCpp block to configure the transpiler. All options use standard Kotlin DSL assignment syntax.

Minimal:

kotlinToCpp {
    // Directory where generated .hpp files are written. 
    // Defaults to <buildDir>/generated/cpp
    outputDirectory = layout.projectDirectory.dir("outputDir/include")
}

Full:

kotlinToCpp {
    // Directory where generated .hpp files are written. 
    // Defaults to <buildDir>/generated/cpp
    outputDirectory = layout.projectDirectory.dir("outputDir/include")

    // Root package namespace. Strips this prefix from output paths.
    // Example: "com.example.app" -> generated files start at "app/"
    rootNamespace = "com.example"

    // Optional list of package prefixes to include (empty = all).
    includePackages = listOf("com.example.features")

    // Fails the build if Kotlin compilation has errors. Defaults to true.
    failOnKotlinErrors = true

    // Writes a `mappings.yaml` source-map for offline debugging tools.
    writeMappingsYaml = false
}

Project Structure¶

Typically, your Kotlin source files should be located in src/main/kotlin. The plugin will mirror the package structure in the specified outputDir.

For example, com.example.features.ControlFlowDemo.kt will be transpiled to outputDir/include/features/ControlFlowDemo.hpp.

Gradle Tasks¶

The plugin adds several tasks to your Gradle project:

Task	Description	Group
`transpileKotlinToCpp`	Transpiles Kotlin sources to C++ headers. Wired into `assemble`.	`build`
`checkCppOutput`	Syntax-checks every emitted `.hpp` with `-fsyntax-only` (skips when no `g++`/`clang++` is on the PATH). Wired into `check`.	`verification`

Runtime Support¶

All transpiled code requires ktox-lib.hpp to be available in your C++ project's include path. The plugin automatically provides this library (it is usually shipped with the plugin or generated during the build).

#include "ktox-lib.hpp"