Kotlin/Native tutorial. Writing a framework and dynamic library #1091

jonnyzzz · 2018-08-08T08:38:33Z

https://youtrack.jetbrains.com/issue/EVAN-5132

Ready for the factual check. English will be improved later

… Kotlin/Native

…for Kotlin/Native

olonho · 2018-08-10T06:06:24Z

pages/docs/tutorials/native/apple-framework.md

+## Generated Framework Headers
+
+Each of created frameworks contains the header file in `<Framework>/Headers/Demo.h`.
+The file does not depend on the target platform (at least with Kotlin/Native v.0.8.1).


Not sure if it is correct wrt some primitive type mappings.

It should definitely be correct for the code above. But it is not correct when Kotlin code has e.g. NSInteger in public signatures.

olonho · 2018-08-10T06:09:09Z

pages/docs/tutorials/native/apple-framework.md

+@property (readonly) NSString *field;
+@end;
+
+__attribute__((objc_subclassing_restricted))


Exact generated bindings content may change without a warning, and we shalln't put too much emphasis on how what is inside, but on hw to use it.

olonho · 2018-08-10T06:12:54Z

pages/docs/tutorials/native/apple-framework.md

+</div>
+
+The Kotlin code is turned into nearly the similar looking
+code in Swift. There are some small differences, so far. We create the Kotlin `object DemoObject`


Maybe we shall cover passing nullable primitives as well (see https://kotlinlang.slack.com/archives/C3SGXARS6/p1533824954000609).

added nullable types and lambdas

olonho · 2018-08-10T06:13:52Z

pages/docs/tutorials/native/apple-framework.md

+
+It may turn out tricky to configure the Objective-C or Swift project in XCode or
+JetBrains AppCode. You should include the Framework into the *General* tab of Target settings
+of XCode project. Also, you may need to fix the `@rpath` to include our Framework folder in the 


Better document how "to fix" rpath.

done. added iOS explanation as well

olonho · 2018-08-10T06:51:59Z

pages/docs/tutorials/native/dynamic-libraries.md

+where you run the compiler:
+- macOS: `demo_api.h` and `libdemo.dylib`
+- Linux: `demo_api.h` and `libdemo.so`
+- Windows: `demo_api.h` and `demo.dll`


On Windows .def file is produced as well. Seems due to small bug it was produced inside Windows temporary files, but it will be fixed with JetBrains/kotlin-native#1859.

fixed in the dynamic libraries branch and #1084

olonho · 2018-08-10T07:46:52Z

pages/docs/tutorials/native/dynamic-libraries.md

+You may want to check [the thread](https://stackoverflow.com/questions/1675351/typedef-struct-vs-struct-definitions)
+for an explanation of that pattern.
+
+We see from that definitions that Kotlin object `DemoObject` is mapped into


As with Objective-C manual not sure if diving into details of generated C headers is a good idea.

SvyatoslavScherbina · 2018-08-13T07:27:23Z

pages/docs/tutorials/native/apple-framework.md

+Now we call the following commands to compile the code into Frameworks
+for macOS, iOS and iOS emulator respectively:
+```bash
+kotlinc lib.kt -produce dynamic -output macOS/Demo


Why not produce framework for macOS too?

it is on the list of 3 commands, what do I miss?

Your first command produces dynamic library (macOS/Demo.dylib), while other commands produce frameworks (iOS*/Demo.framework). Is it OK?

fixed. It was a typoe

SvyatoslavScherbina · 2018-08-13T07:35:03Z

pages/docs/tutorials/native/apple-framework.md

+
+    [Demo forIntegersB:1 s:1 i:3 l:4];
+
+    NSString* ret = [Demo stringsStr:(@"That is string")];


(@"That is string")

Are brackets required here?

SvyatoslavScherbina · 2018-08-13T07:36:52Z

pages/docs/tutorials/native/apple-framework.md

+function `demoObject`, which allows us to get the only instance of the object and to call 
+`DemoObject` methods on it. 
+The standard pattern is used to create an instance of the `DemoClazz` class. We call
+the `[[ DemoDemoClazz alloc] init]` on Objective-C.


Another standard pattern can be used here: [DemoDemoClazz new]. It is available for calling constructor without parameters.

SvyatoslavScherbina · 2018-08-13T07:40:42Z

pages/docs/tutorials/native/apple-framework.md

+The Kotlin code is turned into nearly the similar looking
+code in Swift. There are some small differences, so far. We create the Kotlin `object DemoObject`
+as a class in Swift to access it's methods. We may see from the Objective-C attributes 
+in `<Framework>/Headers/Demo.h` that it is the way to access the object. 


It is not exactly clear from this sentence that DemoObject() doesn't create new instance of DemoObject but returns the existing single one. I would prefer to avoid the word "create".

SvyatoslavScherbina · 2018-08-13T07:42:18Z

pages/docs/tutorials/native/apple-framework.md

+
+Kotlin/Native supports C interop too. Checkout the [Kotlin/Native as a Dynamic Library](dynamic-libraries.html)
+tutorial for that, or have a look at the
+[C Interop](https://github.com/JetBrains/kotlin-native/blob/master/OBJC_INTEROP.md) documentation article


Is this link correct?

OBJC_INTEROP.md doesn't seem to cover anything related to C interop or -produce dynamic. What do I miss?

SvyatoslavScherbina · 2018-08-13T08:42:29Z

pages/docs/tutorials/native/dynamic-libraries.md

+with Kotlin objects from C language. Kotlin/Native has an interop with Objective-C and 
+Swift, and integrates with their reference counters. You may want to find more details
+in the [documentation](https://github.com/JetBrains/kotlin-native/blob/master/OBJC_INTEROP.md)
+or to check the related [TUTORIAL_KOTLIN_macOS_FRAMEWORK_LINK].


Does anything prevent this link from being [apple-framework.html]?

I'll just remove that. The next sentence is just the about the same thing

SvyatoslavScherbina · 2018-08-13T08:48:01Z

pages/docs/tutorials/native/dynamic-libraries.md

+
+Kotlin/Native object references does not support multi-threaded access. It
+might be necessary to host the returned `demo_ExportedSymbols*` pointer
+per thread.


@olonho Isn't demo_ExportedSymbols* the same for all threads?

+1 to the question

SvyatoslavScherbina · 2018-08-13T08:52:13Z

pages/docs/tutorials/native/dynamic-libraries.md

+
+## Using Generated Headers from C
+
+The usage from C not complicated and strait forward. We create a `main.c` file with the following 


strait forward

Is it correct?

nope, fixed

SvyatoslavScherbina · 2018-08-13T08:53:57Z

pages/docs/tutorials/native/dynamic-libraries.md

+  //create Kotlin object instance
+  demo_kref_demo_DemoClazz newInstance 
+          = lib->kotlin.root.demo.DemoClazz.DemoClazz();
+  long result = lib->kotlin.root.demo.DemoClazz.foo(newInstance, 42);


long != demo_KLong. It is better to use either demo_KLong or long long here.

SvyatoslavScherbina · 2018-08-13T08:58:49Z

pages/docs/tutorials/native/dynamic-libraries.md

+On macOS 10.13 with Xcode, we compile the C code and link it with the dynamic library
+with the following command:
+```bash
+gcc main.c libdemo.dylib


On macOS there is no gcc anymore, it is wrapper for clang. It makes some sense to use the latter directly here.

…s for Kotlin/Native

… styles

Merge branch 'tutorial-kn-dynamic-libraries' into tutorial-kn-apple-framework

@rpath

…ble types and lambdas, restructure code and explanations, include more about @rpath and XCode setup

SvyatoslavScherbina · 2018-08-16T07:08:23Z

pages/docs/tutorials/native/apple-framework.md

-are mapped directly.
+are mapped directly. Non-nullable primitive types are mapped transparently.
+Nullable primitive types are mapped into `NSNumber*`.
+You may see both higher order functions `acceptFunF` and `supplyFun` are included,


I don't see the second one.

returned that function back in the samples above, thanks for noticing that

SvyatoslavScherbina · 2018-08-16T07:09:32Z

pages/docs/tutorials/native/apple-framework.md

+are mapped directly. Non-nullable primitive types are mapped transparently.
+Nullable primitive types are mapped into `NSNumber*`.
+You may see both higher order functions `acceptFunF` and `supplyFun` are included,
+and accept Objective-C lambdas.


I'm not sure people often name Objective-C blocks this way.

I'll use blocks too here, thanks!

SvyatoslavScherbina · 2018-08-16T07:22:10Z

pages/docs/tutorials/native/apple-framework.md

+We add the Framework in the `Embedded Binaries` section of the `General` section of
+the *target* configuration. We need to fix the `Framework Search Paths` in the 
+`Build Settings` of the *target* configuration. We shall use the `iOS_emu` folder
+or the `ios_arm64` target for the run in the iOS emulator.  


I can't get the meaning of this sentence. Is it entirely correct?

rewrote it entirely, thanks!

SvyatoslavScherbina · 2018-08-16T07:26:22Z

pages/docs/tutorials/native/apple-framework.md

+
+## XCode for iOS Targets
+
+We add the Framework in the `Embedded Binaries` section of the `General` section of


Is Embedded Binaries feature available for macOS target?

Nope, for bugger Mac you normally include frameworks with the application and configure @rpath appropriately

SvyatoslavScherbina · 2018-08-16T07:30:50Z

pages/docs/tutorials/native/apple-framework.md

 ```bash
 kotlinc lib.kt -produce framework -target macos_x64 -output macOS/Demo
 kotlinc lib.kt -produce framework -target ios_arm64 -output iOS/Demo
 kotlinc lib.kt -produce framework -target ios_x64 -output iOS_emu/Demo
 ```

-The `kotlinc` generates three frameworks for us, named `Demo.framework` under 
-`macOS`, `iOS` and `iOS_emu` folders respectively.
+The `kotlinc` generates three Frameworks for us, named `Demo.framework` under 


What's the purpose of using capital "F" in "Framework"?

SvyatoslavScherbina · 2018-08-16T08:42:22Z

pages/docs/tutorials/native/dynamic-libraries.md


 Kotlin/Native has garbage collection, but it does not help to deal
 with Kotlin objects from C language. Kotlin/Native has an interop with Objective-C and 
 Swift, and integrates with their reference counters. You may want to find more details
 in the [documentation](https://github.com/JetBrains/kotlin-native/blob/master/OBJC_INTEROP.md)
 or to check the related [TUTORIAL_KOTLIN_macOS_FRAMEWORK_LINK].

+NOTE. It is possible to have several Kotlin/Native dynamic libraries in one application, 


Does it really work on macOS?

removed that line for now. It is hard to test, but looks possible

…ials

…Framework

bit of proofreading on it

bit of proofreading

jonnyzzz added 6 commits August 2, 2018 01:18

feat(tutorial): craft main content for dynamic libraries and K/N

5a8c5af

fix(tutorial): improve text under dynamic-libraries.md tutorial for…

9da8987

… Kotlin/Native

feat(tutorial): added Kotlin/Native as an Apple Framework tutorial

24fcbf6

fix(tutorial): casing in dynamic-libraries.md` Kotlin/Native tutorial

b70bd55

add macOS @rpath hint to make examples run

18efe93

fix(tutorial): update tutorials for dynamic libraries and frameworks …

e40e194

…for Kotlin/Native

jonnyzzz self-assigned this Aug 8, 2018

jonnyzzz requested a review from olonho August 8, 2018 08:38

olonho reviewed Aug 10, 2018

View reviewed changes

SvyatoslavScherbina reviewed Aug 13, 2018

View reviewed changes

jonnyzzz added 6 commits August 14, 2018 19:14

fix(tutorial): fix missing parts in the tutorial for dynamic librarie…

f95ab54

…s for Kotlin/Native

fix(tutorial): k/n dynamic libraries tutorial. apply new code samples…

71c241a

… styles

fix version of Kotlin/Native

d16d997

fix(tutorial): k/n apple framework review

b7b402f

fix(tutorial): k/n apple framework and dynamic tutorial

999d1b9

fix(tutorial): merge two tutorials together to simplify reviews

87ee1c4

Merge branch 'tutorial-kn-dynamic-libraries' into tutorial-kn-apple-framework

jonnyzzz mentioned this pull request Aug 15, 2018

Tutorial kn dynamic libraries #1084

Closed

jonnyzzz changed the title ~~[Kotlin/Native Tutorials] Writing a framework in Kotlin and using it in Objective-C~~ Kotlin/Native tutorial. Writing a framework and dynamic library Aug 15, 2018

jonnyzzz added 3 commits August 15, 2018 19:50

fix(tutorial): rework Apple Framework tutorial for K/N. Include nulla…

142953a

…ble types and lambdas, restructure code and explanations, include more about @rpath and XCode setup

fix(tutorial): cleanup and fix typoes

e485a88

fix spelling and typoes

783b10d

SvyatoslavScherbina reviewed Aug 16, 2018

View reviewed changes

fix(tutorial): more fixes for k/n dynamic library and framework tutor…

e89bc8d

…ials

jonnyzzz force-pushed the tutorial-kn-apple-framework branch from d2bbab8 to e89bc8d Compare August 16, 2018 13:24

fix(tutorial): more fixes for k/n framework tutorial: framework, not …

7071f36

…Framework

jonnyzzz assigned B1ggDave Aug 21, 2018

B1ggDave and others added 3 commits August 27, 2018 13:02

proofread watson

ff0ddca

bit of proofreading on it

proofread watson

26b6e18

bit of proofreading

small typoe

cbc14ea

jonnyzzz merged commit 68f7189 into master Aug 29, 2018

jonnyzzz deleted the tutorial-kn-apple-framework branch August 29, 2018 14:14


		[Demo forIntegersB:1 s:1 i:3 l:4];

		NSString* ret = [Demo stringsStr:(@"That is string")];


		## Using Generated Headers from C

		The usage from C not complicated and strait forward. We create a `main.c` file with the following


		## XCode for iOS Targets

		We add the Framework in the `Embedded Binaries` section of the `General` section of

Kotlin/Native tutorial. Writing a framework and dynamic library #1091

Kotlin/Native tutorial. Writing a framework and dynamic library #1091

Conversation

jonnyzzz commented Aug 8, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SvyatoslavScherbina Aug 13, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SvyatoslavScherbina Aug 13, 2018 •

edited

Loading