Added an examplar workflow to LIBRARIES.md.
This commit is contained in:
Alexander Gorshenev
committed by
alexander-gorshenev
alexander-gorshenev
parent
7615c36f2e
commit
9d7e249559
+113
-46
@@ -1,6 +1,116 @@
|
||||
## Kotlin/Native library format
|
||||
# Kotlin/Native libraries
|
||||
|
||||
**WARNING**: the format is *very* preliminary. It is subject to change right under your fingers.
|
||||
## Kotlin compiler specifics
|
||||
|
||||
To produce a library with Kotlin/Native compiler use `-produce library` or `-p library` flag. For example:
|
||||
|
||||
$ kotlic foo.kt -p library -o bar
|
||||
|
||||
the above command will produce a `bar.klib` with compiled contents of `foo.kt`.
|
||||
|
||||
To link a library use `-library <name>` or `-l <name>` flag. For example:
|
||||
|
||||
$ kotlinc qux.kt -l bar
|
||||
|
||||
the above command will produce `program.kexe` out of `qux.kt` and `bar.klib`
|
||||
|
||||
|
||||
## cinterop tool specifics
|
||||
|
||||
The **cinterop** tool produces `.klib` wrappers for native libraries as its main output.
|
||||
For example using the simple `stdio.def` native library definition file provided in your Kotlin/Native distribution
|
||||
|
||||
$ cinterop -def ./samples/csvparser/src/main/c_interop/stdio.def -o stdio
|
||||
|
||||
we obtain `stdio.klib`.
|
||||
|
||||
|
||||
## klib utility
|
||||
|
||||
The **klib** library management utility allows one to inspect and install the libraries.
|
||||
|
||||
The following commands are available.
|
||||
|
||||
To list library contents:
|
||||
|
||||
$ klib contents <name>
|
||||
|
||||
To inspect the bookkeeping details of the library
|
||||
|
||||
$ klib info <name>
|
||||
|
||||
To install the library to the default location use
|
||||
|
||||
$ klib install <name>
|
||||
|
||||
To remove the library from the default repository use
|
||||
|
||||
$ klib remove <name>
|
||||
|
||||
All of the above commands accept an additional `-repository <directory>` argument to specify a repository other than the default one.
|
||||
|
||||
$ klib <command> <name> -repository <directory>
|
||||
|
||||
|
||||
## Several examples
|
||||
|
||||
First lets create a library:
|
||||
|
||||
$ cinterop -h /usr/include/math.h -pkg libc.math -o math
|
||||
|
||||
The library has been created in the current directory:
|
||||
|
||||
$ ls math.klib
|
||||
math.klib
|
||||
|
||||
Now let's check out the contents of the library:
|
||||
|
||||
$ klib contents math
|
||||
|
||||
We can install `math` to the default repository:
|
||||
|
||||
$ klib install math
|
||||
|
||||
Remove any traces of it and its build process from the current directory:
|
||||
|
||||
$ rm -rf ./math*
|
||||
|
||||
Create a very short program and place it into a `sin.kt` :
|
||||
|
||||
import libc.math.*
|
||||
fun main(args: Array<String>) {
|
||||
println(sin(2.0))
|
||||
}
|
||||
|
||||
Now compile the program linking with the library we have just created:
|
||||
|
||||
$ kotlinc sin.kt -l math -o mysin
|
||||
|
||||
And run your program:
|
||||
|
||||
$ ./mysin.kexe
|
||||
0.9092974268256817
|
||||
|
||||
Have fun!
|
||||
|
||||
# Advanced topics
|
||||
|
||||
## Library search sequence
|
||||
|
||||
When given `-library foo` flag, the compiler searches the `foo` library in the following order:
|
||||
|
||||
* Current compilation directory or an absolute path.
|
||||
|
||||
* All repositories specified with `-repo` flag.
|
||||
|
||||
* Libraries installed in the default repository (For now the default is `~/.konan` ).
|
||||
|
||||
* Libraries installed in `$installation/klib` directory.
|
||||
|
||||
|
||||
## The library format
|
||||
|
||||
**WARNING**: the library format is *very* preliminary. It is subject to change right under your fingers. And it can incompatibly change from release to release until Kotlin/Native is stabilized.
|
||||
|
||||
Kotlin/Native libraries are zip files containing predefined
|
||||
directory structure, with the following layout:
|
||||
@@ -22,48 +132,5 @@ directory structure, with the following layout:
|
||||
- General resources such as images. (Not used yet).
|
||||
- manifest - A file in *java property* format describing the library.
|
||||
|
||||
An exemplar layout can be found in **klib** directory of your installation.
|
||||
|
||||
## Library search sequence
|
||||
|
||||
When given **-library foo** flag, the compiler searches the libraries in the following order:
|
||||
|
||||
* Current compilation directory or an absolute path.
|
||||
|
||||
* All repositories specified with *-repo* flag.
|
||||
|
||||
* Libraries installed in .konan directory.
|
||||
|
||||
* Libraries installed in $installation/klib directory.
|
||||
|
||||
## **cinterop* tool specifics
|
||||
|
||||
The **cinterop** tool produces **klib** wrappers for native libraries.
|
||||
|
||||
|
||||
## **klib** utility
|
||||
|
||||
The **klib** library management utility allows one to inspect and install the libraries.
|
||||
|
||||
The following commands are available.
|
||||
|
||||
To list library contents:
|
||||
|
||||
$ klib contents foo
|
||||
|
||||
To ask the details of the library
|
||||
|
||||
$ klib info foo
|
||||
|
||||
To install the library to the default location use
|
||||
|
||||
$ klib install foo
|
||||
|
||||
To install the library to another location run
|
||||
|
||||
$ klib install foo -repository <directory>
|
||||
|
||||
To remove the library from the repository use
|
||||
|
||||
$ klib remove foo [-repository <directory>]
|
||||
An exemplar layout can be found in `klib/stdlib` directory of your installation.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user