Kotlin/Native runtime and stdlib

This folder contains both the Kotlin/Native runtime and Kotlin/Native stdlib.

stdlib

The common code lives in libraries/stdlib. Native-specific sources are:

• src/main/kotlin
• ../Interop/Runtime for kotlinx.cinterop package
• and some parts are written in C++ and considered part of the runtime

:kotlin-native:runtime:stdlibBuildTask builds the standard library. :native:native.tests:stdlibTest will run the standard library tests.

Runtime

The sources should follow the coding convention.

For IDE support, use :kotlin-native:compdb to generate the Compilation Database in kotlin-native/compile_commands.json which is supported by CLion and clangd.

:kotlin-native:runtime:hostRuntime builds the runtime for the current host. :kotlin-native:runtime:<target>Runtime can be used to build for the specific target, or :kotlin-native:runtime:assemble to build for all supported targets.

:kotlin-native:runtime:hostRuntimeTests runs the tests for the current host (the tests will also be rerun with all supported sanitizers). Use -Pgtest_filter= to filter which tests to run (uses Google Test filter syntax). Use -Pgtest_timeout= to limit how much time each test executable can take (accepts values like 30s, 1h15m20s, and so on).

To help with code formatting, .clang-format file is placed in this folder. :kotlin-native:libllvmext:clangFormat task can be used to run git-clang-format -f $(git merge-base origin/master HEAD) -- kotlin-native/libllvmext/, which will format only the changed files. The task accepts optional --parent=<branch> (to specify a branch other than origin/master) and --interactive (which adds -p flag to git-clang-format to interactively accept or reject formatting patches).

Project structure

The runtime is split into multiple modules: the main runtime and a number of optional modules (e.g. objc for ObjC interop support or cms GC with Concurrent Mark&Sweep GC implementation).

The main module contains:

• C++ parts of the Native stdlib
  • scattered around the code
• Core runtime code
  • mm: mostly memory management, the name comes from legacy MM / new MM split which doesn't make much sense anymore
  • lots of files in the root dir
• API declarations for other modules to implement; see Modules for details
• Utilities
  • std_support: additions to C++ stdlib (mostly ported from future standards or from proposals)
  • objc_support: C++ wrappers for ObjC API
  • concurrent: various concurrency primitives like spin locks or thread-state-aware locks
  • lots of files in the root dir

Modules

• Allocator and finalizer
  • Common code and API
  • Default
  • Legacy
• Calls Checker: sanitizer-like instrumentation to help catch external function calls in the wrong thread state (usually indicates a bug in the runtime or the code generator)
  • API
  • No-op
  • Implementation: runtime for the Calls Checker instrumentation; the instrumentation lives in libllvmext
• Compiler interface: API for the compiler (compiled into a bitcode file, that's parsed by the compiler)
• Crash handler
  • API
  • No-op: does nothing
  • Implementation with Breakpad (with additional sources fetched from its repo): only supported on macOS, generates minidump on crash, can be analyzed with minidump-analyzer
• Debug: API for the lldb python plugin
• Exceptions support: used for dynamic compiler caches (untested)
• GC
  • Common code and API
  • CMS: Concurrent Mark&Sweep
  • No-op: does nothing
  • PMCS: Parallel Mark & Concurrent Sweep
  • STMS: Stop-the-world Mark&Sweep
• GC Scheduler (also known as GC Pacer): decides when to trigger the GC
  • Common code and API
  • Adaptive: heuristics based on heap usage
  • Aggressive: triggers GC on every newly encountered safepoint (used as a form of GC stress testing)
  • Manual: GC is only triggered when explicitly requested
• Launcher: defines an entry point, when Kotlin/Native is compiled into an executable
• ObjC interop and Swift Export support
  • Main module parts (files starting with ObjC* and swiftExportRuntime folder)
  • objc: ObjC class definitions that might get renamed in the final binary
  • objCExport: KotlinBase definition that might also get renamed in the final binary; but also used by Swift Export
• Source Info: symbolication support for stack traces
  • API additionally backed by compiler::getSourceInfo in CompilerConstants.hpp
  • Core Symbolication-based: symbolication based on Core Symbolication; only for Apple platforms
  • libbacktrace-based with libbacktrace: symbolication based on libbacktrace; supported on Apple platforms and on Linux
• utfcpp: vendored library for UTF-8 support
• XCTest launcher: defines an entry point, when Kotlin/Native is compiled into test bundle; only for Apple platforms
• Runtime unit tests support:
  • test_support: defines symbols usually defined by the code generator and a GTest test launcher
  • googletest and googlemock are fetched from their repo