Native: use samples only as compiler tests

Remove unrelated parts.
2022-08-26 11:39:18 +02:00
parent 71b8089f33
commit b7337d2e64
19 changed files with 4 additions and 615 deletions
@@ -1,39 +1,4 @@
-# Samples
+This directory contains a set of Kotlin/Native samples.
 They do not demonstrate Kotlin/Native best practices, and are mostly pretty outdated.
-This directory contains a set of samples demonstrating how one can work with Kotlin/Native. The samples can be
+Please visit the website for actual documentation and examples: https://kotlinlang.org/
 built using Gradle build tool. See `README.md` in sample directories to learn more about specific samples and
 the building process.
 The following Kotlin Multiplatform Mobile samples used to be located in this directory, but were superseded:
 * `calculator` - see https://github.com/Kotlin/kmm-basic-sample instead.
 * `cocoapods` - see https://github.com/Kotlin/kmm-with-cocoapods-sample instead.
 More Kotlin Multiplatform Mobile samples can be found here: https://kotlinlang.org/docs/kmm-samples.html.
 The samples that are in this directory mostly illustrate the other use cases for Kotlin/Native:
  * `csvparser` - simple CSV file parser and analyzer
  * `echoServer` - TCP/IP echo server
  * `html5Canvas` - WebAssembly example
  * `libcurl` - using of FTP/HTTP/HTTPS client library `libcurl`
  * `nonBlockingEchoServer` - multi-client TCP/IP echo server using co-routines
  * `objc` - AppKit Objective-C interoperability example for macOS
  * `opengl` - OpenGL/GLUT teapot example
  * `python_extension` - Python extension written in Kotlin/Native
  * `tensorflow` - simple client for TensorFlow Machine Intelligence library
  * `uikit` - UIKit Objective-C interoperability example for iOS
  * `videoplayer` - SDL and FFMPEG-based video and audio player
  * `win32` - trivial Win32 GUI application
  * `workers` - example of using workers API
 **Note**: If the samples are built from a source tree (not from a distribution archive) the compiler built from
 the sources is used. So you must build the compiler and the necessary platform libraries by running
 `./gradlew bundle` from the Kotlin/Native root directory before building samples (see
 [README.md](https://github.com/JetBrains/kotlin-native/blob/master/README.md) for details).
 Alternatively you may remove a line `kotlin.native.home=<...>` from all `gradle.properties` files.
 In this case the Gradle plugin downloads and uses a default compiler for this plugin version.
 One may also build all the samples with one command. To build them using Gradle run:
    ./gradlew buildAllSamples
@@ -32,16 +32,6 @@ val clean by tasks.creating(Delete::class) {
    delete(localRepo)
 }
 val buildSh by tasks.creating(Exec::class) {
    errorOutput = System.out
    isIgnoreExitValue = true
    workingDir = projectDir
    enabled = !isWindows
    if (isLinux || isMacos) {
        commandLine = listOf(projectDir.resolve("build.sh").toString())
    }
 }
 val buildSamplesWithPlatformLibs by tasks.creating {
    dependsOn(":csvparser:assemble")
    dependsOn(":curl:assemble")
@@ -67,10 +57,3 @@ val buildSamplesWithPlatformLibs by tasks.creating {
        dependsOn(":win32:assemble")
    }
 }
 val buildAllSamples by tasks.creating {
    subprojects.forEach {
        dependsOn("${it.path}:assemble")
    }
    finalizedBy(buildSh)
 }
@@ -1,27 +0,0 @@
 #!/usr/bin/env bash
 EXCLUDE=()
 BUILD_SCRIPT="build.sh"
 function isExcluded() {
    CHECKED="${1}"
    for VALUE in $EXCLUDE; do
 	if [ "x$CHECKED" == "x$VALUE" ]; then
 	    return 0
 	fi
    done
    return -1
 }
 for SAMPLE_DIR in *; do
    if [ -d "$SAMPLE_DIR" ] && [ -e "$SAMPLE_DIR/$BUILD_SCRIPT" ]; then
 	echo
 	echo "======================================================"
 	date
 	echo "Building a sample: $SAMPLE_DIR."
 	if ! isExcluded "$SAMPLE_DIR"; then
 	    bash "$SAMPLE_DIR/$BUILD_SCRIPT" || (echo "Cannot build a sample: $SAMPLE_DIR. See log for details." && exit 1)
 	else
 	    echo "The sample excluded."
 	fi
    fi
 done
@@ -1,13 +0,0 @@
 # Code Coverage usage sample
 ⚠️ Kotlin/Native support for code coverage is [far from beign ready](../../CODE_COVERAGE.md). Anything might be broken.
 This example shows how to collect coverage information during execution of the test suite. 
 Please note that this functionality will be incorporated into Gradle plugin so you won't need to do it by hand in the nearest future. 
 ### Prerequisites
 `createCoverageReport` task requires `llvm-profdata` and `llvm-cov` to be added to the `$PATH`.  
 In case of macOS, use tools from Xcode (`/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin`).  
 For Windows and Linux, use the ones from Kotlin/Native LLVM distribution (e.g. `$HOME/.konan/dependencies/clang-llvm-8.0.0-linux-x86-64/bin`).
 ### Usage
 Just run `createCoverageReport` task.
@@ -1,14 +0,0 @@
 # CSV parser
 This example shows how one could implement simple comma separated values reader and parser in Kotlin.
 A sample data [European Mammals Red List for 2009](https://data.europa.eu/euodp/en/data/dataset?res_format=CSV)
 from EU is being used.
 To build use `../gradlew assemble`.
 To run use `../gradlew runReleaseExecutableCsvParser` or execute the program directly:
    ./build/bin/csvParser/main/release/executable/csvparser.kexe ./European_Mammals_Red_List_Nov_2009.csv --column 4 --count 100
 It will print number of all unique entries in fifth column
 (Family, zero-based index) in first 100 rows of the CSV file.
@@ -1,13 +0,0 @@
 # HTTP client
 This example shows how to communicate with libcurl, HTTP/HTTPS/FTP/etc client library and how to
 depend on an artifact published in a maven repository. The sample depends on a library
 built by [libcurl sample](../libcurl) so you need to run it first.
 To build use `../gradlew assemble`.
 To run use `../gradlew runReleaseExecutableCurl` or execute the program directly:
    ./build/bin/curl/main/release/executable/curl.kexe 'https://www.jetbrains.com/'
 It will perform HTTP get and print out the data obtained.
@@ -1,15 +0,0 @@
 # Sockets demo
 To build use `../gradlew assemble`.
 To run use `../gradlew runReleaseExecutableEchoServer` or execute the program directly:
    ./build/bin/echoServer/main/release/executable/echoServer.kexe 3000 &
 Test the server by connecting to it, for example with telnet:
    telnet localhost 3000
 Write something to console and watch server echoing it back.
 ~~Quit telnet by pressing ctrl+] ctrl+D~~
@@ -1,9 +0,0 @@
 # Shared global state
 This example shows how one could implement global shared state using interop mechanisms.
 To build use `../gradlew assemble`.
 To run use `../gradlew runReleaseExecutableGlobalState` or execute the program directly:
    ./build/bin/globalState/main/release/executable/globalState.kexe
@@ -1,15 +0,0 @@
 # HTML5 Canvas
 This sample shows how to use Kotlin/Native to build a WebAssembly application and how to call JavaScript functions
 from a Kotlin/Native code.
 > __Note__: If you build this sample not from the Kotlin/Native repository, you need to specify a path to a
 Kotlin/Native distribution. Add the following snippet in `gradle.properties`:
 >```
 >kotlin.native.home=<path-to-distribution>
 >```
 > The default distribution path is `$HOME/.konan/kotlin-native-<macos|linux|windows>-<version>`.
 To build use `../gradlew assemble`.
 To run use `../gradlew runProgram`.
@@ -1,13 +0,0 @@
 # Curl interop library
 This example shows how to build and publish an interop library to communicate with the libcurl,
 HTTP/HTTPS/FTP/etc client library.
 Install libcurl development files. For Mac - `brew install curl`. For Debian-like Linux - use `apt-get install libcurl4-openssl-dev` or `apt-get install libcurl4-gnutls-dev`.
 For Windows - `pacman -S mingw-w64-x86_64-curl` in MinGW64 console, if you do
 not have MSYS2-MinGW64 installed - install it first as described in http://www.msys2.org
 To build use `../gradlew assemble`.
 To publish the library into a local repo use `../gradlew publish`.
@@ -1,25 +0,0 @@
 # Non-blocking echo server demo
 This sample shows how to implement multi-client server using coroutines.
 IO operations are implemented using non-blocking OS calls, and instead coroutines
 are being suspended and resumed whenever relevant.
 Thus, while server can process multiple connections concurrently,
 each individual connection handler is written in simple linear manner.
 To build use `../gradlew assemble`.
 To run use `../gradlew runReleaseExecutableNonBlockingEchoServer` or execute the program directly:
    ./build/bin/nonBlockingEchoServer/main/release/executable/nonBlockingEchoServer.kexe 3000 &
 Test the server by connecting to it, for example with telnet:
    telnet localhost 3000
 Write something to console and watch server echoing it back.
 Concurrently connect from another terminal. Note that each connection gets its own
 connection id prefixed to echo response.
 ~~Quit telnet by pressing ctrl+] ctrl+D~~
@@ -1,13 +0,0 @@
 # OpenGL application
 This example shows interaction with OpenGL library, to render classical 3D test model. Linux build requires `apt-get install freeglut3-dev` or similar,
 MacOS shall work as is.
 To build use `../gradlew assemble`.
 To run use `../gradlew runReleaseExecutableOpengl` or execute the program directly:
    ./build/bin/opengl/main/release/executable/opengl.kexe
 It will render 3D model of teapot. Feel free to experiment with it, the whole power of OpenGL
 is at your hands.
@@ -1,30 +0,0 @@
 # TensorFlow demo
 Small Hello World calculation on the [TensorFlow](https://www.tensorflow.org/) backend,
 arranging simple operations into a graph and running it on a session.
 Like other [TensorFlow clients](https://www.tensorflow.org/extend/language_bindings)
 (e. g. for [Python](https://github.com/tensorflow/tensorflow/tree/master/tensorflow/python/client)),
 this example is built on top of the
 [TensorFlow C API](https://github.com/tensorflow/tensorflow/blob/r1.1/tensorflow/c/c_api.h),
 showing how a TensorFlow client in Kotlin/Native could look like.
 ## Installation
    ./downloadTensorflow.sh
 will install [TensorFlow for C](https://www.tensorflow.org/versions/r1.1/install/install_c) into
 `$HOME/.konan/third-party/tensorflow` (if not yet done). One may override the location of
 `third-party/tensorflow` by setting the `KONAN_DATA_DIR` environment variable.
 To build use `../gradlew assemble`.
 Then run
    ../gradlew runReleaseExecutableTensorflow
 Alternatively you can run the artifact directly through
    ./build/bin/tensorflow/main/release/executable/tensorflow.kexe
 You may need to specify `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH` to `$HOME/.konan/third-party/tensorflow/lib`
 if the TensorFlow dynamic library cannot be found.
@@ -1,24 +0,0 @@
 # iOS UIKit sample
 This example shows how to write iOS UI applications in Kotlin, and run them on
 Apple devices, such as an iPhone.
 To build and run the sample do the following:
 0.  Optional: install Kotlin Xcode plugin: https://github.com/touchlab/xcode-kotlin to have
    syntax highlighting and better debugging support.
 1.  Open  `UIKitSample.xcodeproj` with Xcode, set development team to your own
   and make bundle ID unique in project settings.
  or
 1a.  Similarly modify `bundleIdPrefix` and `DEVELOPMENT_TEAM` in `project.yml` and
    then generate Xcode project with `xcodegen` (https://github.com/yonaskolb/XcodeGen/).
 2.  Now build and run the application with Xcode on a connected iPhone  or simulator.
 Note that in this example we do not use storyboards, and instead create user interface
 components programmatically. Defining UI with storyboards in pure Kotlin iOS applications
 is supported as well.
@@ -1,15 +1,7 @@
-# Simple video player
+ffmpeg and SDL2 are needed for the compilation, i.e.
 This example shows how one could implement a video player in Kotlin.
 Almost any video file supported by ffmpeg could be played with it.
 ffmpeg and SDL2 is needed for that to work, i.e.
     port install ffmpeg-devel
     brew install ffmpeg sdl2
     apt install libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libswresample-dev
     apt install libsdl2-dev
     pacman -S mingw-w64-x86_64-SDL2 mingw-w64-x86_64-ffmpeg
 To build use `../gradlew assemble`.
 To run use `./build/bin/videoPlayer/main/release/executable/videoplayer.kexe <file>.mp4`.
@@ -1,28 +0,0 @@
 # watchOS sample
 This example shows how to write watchOS UI applications in Kotlin, and run them on
 Apple Watch or simulator.
 To build and run the sample do the following:
 0.  Optional: install Kotlin Xcode plugin: https://github.com/touchlab/xcode-kotlin to have
    syntax highlighting and better debugging support.
 1.  Open `watchosSample.xcodeproj` set development team to your own and make bundle ID unique
    in project setting.
   or
 1a.  Similarly modify `bundleIdPrefix`, `DEVELOPMENT_TEAM` and `WKAppBundleIdentifier` in `project.yml`
    and generate Xcode project with `xcodegen` (https://github.com/yonaskolb/XcodeGen/).
    Open generated `watchosSample.xcodeproj` with Xcode.
 2. Update property `WKAppBundleIdentifier` in `plists/Ext/Info.plist` with new ID of the watch application,
   if not regenerating project.
 3.  Now build and run the application on a connected iPhone with paired Apple Watch or simulator.
 Note that in this example we do not use storyboards, and instead create user interface
 components programmatically.
 First run of application on the physical watch could be blocked, so run it from watch menu
 and explicitly confirm that developer is trusted.
@@ -1,7 +0,0 @@
 # WIN32 Hello World
 To build use `..\gradlew assemble`.
 To run use `..\gradlew runReleaseExecutableWin32` or execute the program directly:
    `.\build\exe\main\release\MessageBox.exe`.
@@ -1,43 +0,0 @@
 # Workers
 This example shows how one could implement computation offload to other workers
 (usually mapped to OS threads) and transfer data back and forth between workers.
 Idea of workers is to avoid most common problems with concurrent programming, related
 to simultaneous computations on the same data. Instead, each object belongs to
 one or other worker's object graph, but could be disconnected from one worker
 and connected to other worker. This relies on the fact that memory management
 engine can ensure, that one worker doesn't keep references to certain object and
 whatever it refers to, and so the object could be safely transferred to another worker.
 Workers do not share mutable state, but share executable code of the program and some
 immutable data, such as immutable blobs. But Kotlin objects can be transferred
 between workers, as long, as they do not refer to objects, having external references.
 The transfer is implemented with the function `execute()` having the following signature
    fun <T1, T2> execute(
            mode: TransferMode,
            producer: () -> T1,
            @VolatileLambda job: (T1) -> T2
    ): Future<T2>
 Kotlin/Native runtime invokes `producer()` function, and makes sure object it produces
 have a property, that no external references to subgraph rooted by this object, exists.
 If property doesn't hold, either (depending on `mode` argument) exception is being thrown
 or program may crash unexpectedly.
 Then, pointer to stateless lambda `job` along with the stable pointer to parameter object
 is being added to the target worker's queue, and `Future` object matching to the query
 is being created. Once worker peeks the job from the queue, it executes stateless lambda
 with object provided, and stores stable pointer to result in future's data. Whenever
 future is being consumed, object is passed to the consumer's callback.
 This particular example starts several workers, and gives them some computational jobs.
 Then it continues execution, and waits on future objects encapsulating the
 computation results. Afterwards, worker execution termination is requested with the
 `requestTermination()` operation.
 To build use `../gradlew assemble`.
 To run use `../gradlew runReleaseExecutableWorkers` or execute the program directly:
    ./build/bin/workers/main/release/executable/workers.kexe