diff --git a/BUILD b/BUILD index e66618196..6c69195fb 100644 --- a/BUILD +++ b/BUILD @@ -86,6 +86,7 @@ cc_binary( "src/idl_gen_cpp.cpp", "src/idl_gen_dart.cpp", "src/idl_gen_general.cpp", + "src/idl_gen_kotlin.cpp", "src/idl_gen_go.cpp", "src/idl_gen_grpc.cpp", "src/idl_gen_js_ts.cpp", diff --git a/CMakeLists.txt b/CMakeLists.txt index c7da97f5a..029ccb5d2 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -83,6 +83,7 @@ set(FlatBuffers_Compiler_SRCS src/idl_gen_cpp.cpp src/idl_gen_dart.cpp src/idl_gen_general.cpp + src/idl_gen_kotlin.cpp src/idl_gen_go.cpp src/idl_gen_js_ts.cpp src/idl_gen_php.cpp diff --git a/docs/source/Compiler.md b/docs/source/Compiler.md index 49a3d8f6e..7889abdc2 100644 --- a/docs/source/Compiler.md +++ b/docs/source/Compiler.md @@ -23,6 +23,8 @@ For any schema input files, one or more generators can be specified: - `--java`, `-j` : Generate Java code. +- `--kotlin`, `-k` : Generate Kotlin code. + - `--csharp`, `-n` : Generate C# code. - `--go`, `-g` : Generate Go code. diff --git a/docs/source/FlatBuffers.md b/docs/source/FlatBuffers.md index 7cc93b92c..dc77500de 100644 --- a/docs/source/FlatBuffers.md +++ b/docs/source/FlatBuffers.md @@ -4,7 +4,7 @@ FlatBuffers {#flatbuffers_index} # Overview {#flatbuffers_overview} [FlatBuffers](@ref flatbuffers_overview) is an efficient cross platform -serialization library for C++, C#, C, Go, Java, JavaScript, Lobster, Lua, TypeScript, PHP, Python, and Rust. +serialization library for C++, C#, C, Go, Java, Kotlin, JavaScript, Lobster, Lua, TypeScript, PHP, Python, and Rust. It was originally created at Google for game development and other performance-critical applications. @@ -51,7 +51,7 @@ under the Apache license, v2 (see LICENSE.txt). needed (faster and more memory efficient than other JSON parsers). - Java and Go code supports object-reuse. C# has efficient struct based + Java, Kotlin and Go code supports object-reuse. C# has efficient struct based accessors. - **Cross platform code with no dependencies** - C++ code will work @@ -108,7 +108,7 @@ sections provide a more in-depth usage guide. present for every object instance. - Use `flatc` (the FlatBuffer compiler) to generate a C++ header (or - Java/C#/Go/Python.. classes) with helper classes to access and construct + Java/Kotlin/C#/Go/Python.. classes) with helper classes to access and construct serialized data. This header (say `mydata_generated.h`) only depends on `flatbuffers.h`, which defines the core functionality. @@ -132,6 +132,8 @@ sections provide a more in-depth usage guide. own programs. - How to [use the generated Java/C# code](@ref flatbuffers_guide_use_java_c-sharp) in your own programs. +- How to [use the generated Kotlin code](@ref flatbuffers_guide_use_kotlin) + in your own programs. - How to [use the generated Go code](@ref flatbuffers_guide_use_go) in your own programs. - How to [use the generated Lua code](@ref flatbuffers_guide_use_lua) in your diff --git a/docs/source/KotlinUsage.md b/docs/source/KotlinUsage.md new file mode 100644 index 000000000..092fcd7f5 --- /dev/null +++ b/docs/source/KotlinUsage.md @@ -0,0 +1,84 @@ +Use in Kotlin {#flatbuffers_guide_use_kotlin} +============== + +## Before you get started + +Before diving into the FlatBuffers usage in Kotlin, it should be noted that +the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to +general FlatBuffers usage in all of the supported languages (including K). + +This page is designed to cover the nuances of FlatBuffers usage, specific to Kotlin. + +You should also have read the [Building](@ref flatbuffers_guide_building) +documentation to build `flatc` and should be familiar with +[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and +[Writing a schema](@ref flatbuffers_guide_writing_schema). + +## Kotlin and FlatBuffers Java code location + +Code generated for Kotlin currently uses the flatbuffers java runtime library. That means that Kotlin generated code can only have Java virtual machine as target architecture (which includes Android). Kotlin Native and Kotlin.js are currently not supported. + +The code for the FlatBuffers Java library can be found at +`flatbuffers/java/com/google/flatbuffers`. You can browse the library on the +[FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/ +java/com/google/flatbuffers). + +## Testing FlatBuffers Kotlin + +The test code for Java is located in [KotlinTest.java](https://github.com/google +/flatbuffers/blob/master/tests/KotlinTest.kt). + +To run the tests, use [KotlinTest.sh](https://github.com/google/ +flatbuffers/blob/master/tests/KotlinTest.sh) shell script. + +*Note: These scripts require that [Kotlin](https://kotlinlang.org/) is installed.* + +## Using the FlatBuffers Kotlin library + +*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth +example of how to use FlatBuffers in Kotlin.* + +FlatBuffers supports reading and writing binary FlatBuffers in Kotlin. + +To use FlatBuffers in your own code, first generate Java classes from your +schema with the `--kotlin` option to `flatc`. +Then you can include both FlatBuffers and the generated code to read +or write a FlatBuffer. + +For example, here is how you would read a FlatBuffer binary file in Kotlin: +First, import the library and generated code. Then, you read a FlatBuffer binary +file into a `ByteArray`. You then turn the `ByteArray` into a `ByteBuffer`, which you +pass to the `getRootAsMyRootType` function: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.kt} + import MyGame.Example.* + import com.google.flatbuffers.FlatBufferBuilder + + // This snippet ignores exceptions for brevity. + val data = RandomAccessFile(File("monsterdata_test.mon"), "r").use { + val temp = ByteArray(it.length().toInt()) + it.readFully(temp) + temp + } + + val bb = ByteBuffer.wrap(data) + val monster = Monster.getRootAsMonster(bb) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Now you can access the data from the `Monster monster`: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.kt} + val hp = monster.hp + val pos = monster.pos!!; +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + + +## Differences between Kotlin and Java code + +Kotlin generated code was designed to be as close as possible to the java counterpart, as for now, we only support kotlin on java virtual machine. So the differences in implementation and usage are basically the ones introduced by the Kotlin language itself. You can find more in-depth information [here](https://kotlinlang.org/docs/reference/comparison-to-java.html). + +The most obvious ones are: + +* Fields as accessed as Kotlin [properties](https://kotlinlang.org/docs/reference/properties.html) +* Static methods are accessed in [companion object](https://kotlinlang.org/docs/reference/classes.html#companion-objects) \ No newline at end of file diff --git a/docs/source/Tutorial.md b/docs/source/Tutorial.md index 62abe7ffb..18818a0af 100644 --- a/docs/source/Tutorial.md +++ b/docs/source/Tutorial.md @@ -23,6 +23,7 @@ Please select your desired language for our quest: