From 14cb7621335e5cacdc5278dac15440d432bd3f0d Mon Sep 17 00:00:00 2001 From: Svyatoslav Scherbina Date: Mon, 15 Mar 2021 14:09:00 +0000 Subject: [PATCH] Update the docs to reflect Kotlin/Native merge to kotlin repo Also: * Revamp kotlin-native/README.md a bit: make it more up-to-date, add useful links * Remove "composite build" section from ReadMe.md: it was used for Kotlin + Kotlin/Native composite; this is no longer required. --- ReadMe.md | 24 +---------- kotlin-native/README.md | 89 ++++++++++++++++++++++++++--------------- 2 files changed, 59 insertions(+), 54 deletions(-) diff --git a/ReadMe.md b/ReadMe.md index 3649308040a..b1ae553e2bb 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -106,6 +106,8 @@ To reproduce TeamCity build use `-Pteamcity=true` flag. Local builds don't run p **OPTIONAL:** Some artifacts, mainly Maven plugin ones, are built separately with Maven. Refer to [libraries/ReadMe.md](libraries/ReadMe.md) for details. +To build Kotlin/Native, see +[kotlin-native/README.md](kotlin-native/README.md#building-from-source). ### Building for different versions of IntelliJ IDEA and Android Studio @@ -145,28 +147,6 @@ From this root project there are Run/Debug Configurations for running `IDEA` or * Run the `IDEA` run configuration in the project * A child IntelliJ IDEA with the Kotlin plugin will then startup -### Including into composite build - -To include kotlin compiler into [composite build](https://docs.gradle.org/current/userguide/composite_builds.html) you need to define `dependencySubstitution` for `kotlin-compiler` module in `settings.gradle.kts` - -```Kotlin -includeBuild("/path/to/kotlin") { - dependencySubstitution { - substitute(module("org.jetbrains.kotlin:kotlin-compiler")) - .with(project(":include:kotlin-compiler")) - } -} -``` - -or in `settings.gradle` - -```Groovy -includeBuild('/path/to/kotlin') { - dependencySubstitution { - substitute module('org.jetbrains.kotlin:kotlin-compiler') with project(':include:kotlin-compiler') - } -} -``` # License Kotlin is distributed under the terms of the Apache License (Version 2.0). See [license folder](license/README.md) for details. diff --git a/kotlin-native/README.md b/kotlin-native/README.md index 3134a538e5a..d890b7362fe 100644 --- a/kotlin-native/README.md +++ b/kotlin-native/README.md @@ -1,5 +1,3 @@ -[![official project](http://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) -[![version](https://img.shields.io/badge/dynamic/json.svg?color=orange&label=latest%20version&query=%24.tag_name&url=https%3A%2F%2Fgithub.com%2FJetBrains%2Fkotlin-native%2Freleases%2Flatest)](https://github.com/JetBrains/kotlin-native/releases/latest) # Kotlin/Native # _Kotlin/Native_ is an LLVM backend for the Kotlin compiler, runtime @@ -10,55 +8,82 @@ virtual machines are not desirable or possible (such as iOS or embedded targets) or where a developer is willing to produce a reasonably-sized self-contained program without the need to ship an additional execution runtime. +## Using published Kotlin/Native versions + +The most complete experience with Kotlin/Native can be achieved by using +[Gradle](https://kotlinlang.org/docs/native-gradle.html), +[IntelliJ IDEA](https://kotlinlang.org/docs/native-get-started.html) or +[Android Studio with KMM plugin](https://kotlinlang.org/docs/mobile/create-first-app.html) +if you target iOS. + +If you are interested in using Kotlin/Native for iOS, then +[Kotlin Multiplatform Mobile portal](https://kotlinlang.org/lp/mobile/) +might be useful for you. + +Command line compiler is also +[available](https://kotlinlang.org/docs/native-command-line-compiler.html). + +More information can be found in the overviews of +[Kotlin/Native](https://kotlinlang.org/docs/native-overview.html) +and [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html). + +On macOS Kotlin/Native requires Xcode 11 or newer. + +## Building from source + Prerequisites: -* install JDK for your platform, instead of JRE. The build requires ```tools.jar```, which is not included in JRE; -* on macOS install Xcode 11 (Xcode 12.0 is required to compile Kotlin/Native from sources) +* configure Kotlin build as [specified in main readme](../ReadMe.md#build-environment-requirements) +* at the root directory of the repository, + create `local.properties` file with `kotlin.native.enabled=true` line +* on macOS install Xcode 12 or newer * on Fedora 26+ ```yum install ncurses-compat-libs``` may be needed * on recent Ubuntu ```apt install libncurses5``` is needed -To compile from sources use following steps: +The commands below should be run from either repository root or this (`kotlin-native/`) directory. +For the latter, `:kotlin-native:` task name prefix can be omitted. -First, download dependencies: +To compile the basic compiler distribution from sources, run following command: - ./gradlew dependencies:update + ./gradlew :kotlin-native:dist -Then, build the compiler and libraries: +It will build compiler and stdlib for host target, without +[platform libraries](https://kotlinlang.org/docs/native-platform-libs.html). - ./gradlew bundle +To get platform libraries, add `distPlatformLibs` task, e.g. -To build with experimental targets support compile with `-Porg.jetbrains.kotlin.native.experimentalTargets`. + ./gradlew :kotlin-native:dist :kotlin-native:distPlatformLibs -The build can take about an hour on a Macbook Pro. -To run a shorter build with only the host compiler and libraries, run: +To run the full build: - ./gradlew dist distPlatformLibs + ./gradlew :kotlin-native:bundle -To include Kotlin compiler in [composite build](https://docs.gradle.org/current/userguide/composite_builds.html) and build -against it, use the `kotlinProjectPath` project property: +This will produce compiler and libraries for all supported targets. +The full build can take about an hour on a Macbook Pro. - ./gradlew dist -PkotlinProjectPath=path/to/kotlin/project +After any of the commands above, `./dist` will contain Kotlin/Native distribution. +You can use it like a distribution of +[command-line compiler](https://kotlinlang.org/docs/native-command-line-compiler.html). -It's possible to include in a composite build both Kotlin compiler and Kotlin/Native Shared simultaneously. +Or configure Gradle to use it -- just add the following line to +`gradle.properties` in your Gradle project: -After that, you should be able to compile your programs like this: + kotlin.native.home=/path/to/kotlin/kotlin-native/dist - export PATH=./dist/bin:$PATH - kotlinc hello.kt -o hello +To compile your programs with command-line compiler, use: + + ./dist/bin/kotlinc-native hello.kt -o hello For an optimized compilation, use `-opt`: - kotlinc hello.kt -o hello -opt + ./dist/bin/kotlinc-native hello.kt -o hello -opt + +### Interoperability + +To import a C or Objective-C library, use `./dist/bin/cinterop` tool. +See the [documentation](https://kotlinlang.org/docs/native-c-interop.html) for more details. + +### Running tests For tests, use: - ./gradlew backend.native:tests:run - -To generate interoperability stubs, create a library definition file -(refer to [`samples/tetris/.../sdl.def`](https://github.com/JetBrains/kotlin-native/blob/master/samples/tetris/src/nativeInterop/cinterop/sdl.def)), and run the `cinterop` tool like this: - - cinterop -def lib.def - -See the provided [samples](https://github.com/JetBrains/kotlin-native/tree/master/samples) and [`INTEROP.md`](https://github.com/JetBrains/kotlin-native/blob/master/INTEROP.md) for more details. - -The Interop tool generates a library in the `.klib` library format. See [`LIBRARIES.md`](https://github.com/JetBrains/kotlin-native/blob/master/LIBRARIES.md) -for more details on this file format. + ./gradlew :kotlin-native:backend.native:tests:run