diff --git a/docs/topics/native/lib.h b/docs/topics/native/lib.h new file mode 100644 index 00000000000..8bb5a4b998c --- /dev/null +++ b/docs/topics/native/lib.h @@ -0,0 +1,10 @@ +#ifndef LIB2_H_INCLUDED +#define LIB2_H_INCLUDED + +void ints(char c, short d, int e, long f); +void uints(unsigned char c, unsigned short d, unsigned int e, unsigned long f); +void doubles(float a, double b); + +#endif + +// if you use C++ and overloaded functions -> `extern "C"` block is missing -- https://stackoverflow.com/questions/1041866/what-is-the-effect-of-extern-c-in-c -- \ No newline at end of file diff --git a/docs/topics/native/mapping-primitive-data-types-from-c.md b/docs/topics/native/mapping-primitive-data-types-from-c.md index c0240a1a8c6..73f02a723da 100644 --- a/docs/topics/native/mapping-primitive-data-types-from-c.md +++ b/docs/topics/native/mapping-primitive-data-types-from-c.md @@ -1,68 +1,45 @@ [//]: # (title: Mapping primitive data types from C – tutorial) -> The C libraries import is [Experimental](components-stability.md#stability-levels-explained). -> All Kotlin declarations generated by the `cinterop` tool from C libraries -> should have the `@ExperimentalForeignApi` annotation. -> -> Native platform libraries shipped with Kotlin/Native (like Foundation, UIKit, and POSIX), -> require opt-in only for some APIs. In such cases, you get an IDE warning. -> -{type="warning"} - -In this tutorial, you will learn what C data types are visible in Kotlin/Native and vice versa. You will: -- See what [Data types are in C language](#types-in-c-language). -- Create a [tiny C Library](#example-c-library) that uses those types in exports. -- [Inspect generated Kotlin APIs from a C library](#inspect-generated-kotlin-apis-for-a-c-library). -- Find how [Primitive types in Kotlin](#primitive-types-in-kotlin) are mapped to C. - -## Types in C language - -What types are there in the C language? Let's take the -[C data types](https://en.wikipedia.org/wiki/C_data_types) article from Wikipedia as a basis. -There are following types in the C programming language: -- basic types `char, int, float, double` with modifiers `signed, unsigned, short, long` -- structures, unions, arrays -- pointers -- function pointers - -There are also more specific types: -- boolean type (from [C99](https://en.wikipedia.org/wiki/C99)) -- `size_t` and `ptrdiff_t` (also `ssize_t`) -- fixed width integer types, such as `int32_t` or `uint64_t` (from [C99](https://en.wikipedia.org/wiki/C99)) - -There are also the following type qualifiers in the C language: `const`, `volatile`, `restrict`, `atomic`. - -The best way to see what C data types are visible in Kotlin is to try it. +* goal + * what C data types are visible | Kotlin/Native <- & -> vice versa + * see what [Data types | C language](#types-in-c-language) + * create a [tiny C Library](#example-c-library) / uses those types | exports + * [inspect generated Kotlin APIs -- from a -- C library](#inspect-generated-kotlin-apis-for-a-c-library) + * [primitive types in Kotlin -- are mapped to -- C](#primitive-types-in-kotlin) + +## Types | C language + +* see [C data types article](https://en.wikipedia.org/wiki/C_data_types) + - basic types `char, int, float, double` / modifiers `signed, unsigned, short, long` + - structures, unions, arrays + - pointers + - function pointers + - other specific types + - boolean type (from [C99](https://en.wikipedia.org/wiki/C99)) + - `size_t` and `ptrdiff_t` (also `ssize_t`) + - fixed width integer types, such as `int32_t` or `uint64_t` (from [C99](https://en.wikipedia.org/wiki/C99)) + +* type qualifiers + * `const`, + * `volatile`, + * `restrict`, + * `atomic` ## Example C library -Create a `lib.h` file to see how C functions are mapped into Kotlin: +* see `lib.h` + * goal + * how C functions -- are mapped into -- Kotlin -```c -#ifndef LIB2_H_INCLUDED -#define LIB2_H_INCLUDED - -void ints(char c, short d, int e, long f); -void uints(unsigned char c, unsigned short d, unsigned int e, unsigned long f); -void doubles(float a, double b); - -#endif -``` - -The file is missing the `extern "C"` block, which is not needed for this example, but may be -necessary if you use C++ and overloaded functions. The -[C++ compatibility thread](https://stackoverflow.com/questions/1041866/what-is-the-effect-of-extern-c-in-c) on Stackoverflow -contains more details on this. - -For every set of `.h` files, -you will be using the [`cinterop` tool](native-c-interop.md) -from Kotlin/Native to generate a Kotlin/Native library, -or `.klib`. The generated library will bridge calls from Kotlin/Native to C. It includes -respective Kotlin declarations for the definitions form the `.h` files. -It is only necessary to have a `.h` file to run the `cinterop` tool. And you do not need to create a -`lib.c` file, unless you want to compile and run the example. -More details on this are covered in the [C interop](native-c-interop.md) page. It is enough for -the tutorial to create the `lib.def` file with the following content: +* [`cinterop` tool](native-c-interop.md) + * from `.h` -- you can generate a -- Kotlin/Native library (== `.klib` ) / + * calls from Kotlin/Native -- are bridged to -- C +* TODO: +* It includes respective Kotlin declarations for the definitions form the `.h` files. +It is only necessary to have a `.h` file to run the `cinterop` tool. +And you do not need to create a `lib.c` file, unless you want to compile and run the example. +More details on this are covered in the [C interop](native-c-interop.md) page. +It is enough for the tutorial to create the `lib.def` file with the following content: ```c headers = lib.h @@ -70,10 +47,9 @@ headers = lib.h You may include all declarations directly into the `.def` file after a `---` separator. It can be helpful to include macros or other C defines into the code generated by the `cinterop` tool. -Method bodies are compiled and fully included into the binary too. Use -that feature to have a runnable example without a need for a C compiler. -To implement that, you need to add implementations to the C functions from the `lib.h` file, -and place these functions into a `.def` file. +Method bodies are compiled and fully included into the binary too. +Use that feature to have a runnable example without a need for a C compiler. +To implement that, you need to add implementations to the C functions from the `lib.h` file, and place these functions into a `.def` file. You will have the following `interop.def` result: ```c @@ -89,6 +65,8 @@ The `interop.def` file is enough to compile and run the application or open it i Now it is time to create project files, open the project in [IntelliJ IDEA](https://jetbrains.com/idea) and run it. +* TODO: + ## Inspect generated Kotlin APIs for a C library While it is possible to use the command line, either directly or @@ -236,27 +214,24 @@ as it is usually an 8-bit signed value. ## Fix the code -You've seen all definitions and it is the time to fix the code. -Run the `runDebugExecutableNative` Gradle task [in IDE](native-get-started.md) -or use the following command to run the code: - -```bash -./gradlew runDebugExecutableNative -``` +* run -The final code in the `hello.kt` file may look like that: + ```bash + ./gradlew runDebugExecutableNative + ``` +* final code | `hello.kt` -```kotlin -import interop.* - -fun main() { - println("Hello Kotlin/Native!") - - ints(1, 2, 3, 4) - uints(5, 6, 7, 8) - doubles(9.0f, 10.0) -} -``` + ```kotlin + import interop.* + + fun main() { + println("Hello Kotlin/Native!") + + ints(1, 2, 3, 4) + uints(5, 6, 7, 8) + doubles(9.0f, 10.0) + } + ``` ## Next steps