Move everything under kotlin-native folder

I was forced to manually do update the following files, because otherwise they would be ignored according .gitignore settings. Probably they should be deleted from repo. Interop/.idea/compiler.xml Interop/.idea/gradle.xml Interop/.idea/libraries/Gradle__org_jetbrains_kotlin_kotlin_runtime_1_0_3.xml Interop/.idea/libraries/Gradle__org_jetbrains_kotlin_kotlin_stdlib_1_0_3.xml Interop/.idea/modules.xml Interop/.idea/modules/Indexer/Indexer.iml Interop/.idea/modules/Runtime/Runtime.iml Interop/.idea/modules/StubGenerator/StubGenerator.iml backend.native/backend.native.iml backend.native/bc.frontend/bc.frontend.iml backend.native/cli.bc/cli.bc.iml backend.native/cli.bc/src/org/jetbrains/kotlin/cli/bc/K2Native.kt backend.native/cli.bc/src/org/jetbrains/kotlin/cli/bc/K2NativeCompilerArguments.kt backend.native/tests/link/lib/foo.kt backend.native/tests/link/lib/foo2.kt backend.native/tests/teamcity-test.property
2020-10-27 21:00:28 +03:00
parent 91e4162dad
commit f624800b84
2830 changed files with 0 additions and 0 deletions
@@ -0,0 +1,67 @@
+# Code Coverage
+Kotlin/Native has a code coverage support that is based on Clang's 
+[Source-based Code Coverage](https://clang.llvm.org/docs/SourceBasedCodeCoverage.html).
+ 
+**Please note**:
+1. Coverage support is in it's very early days and is in active development. Known issues are:
+    * Coverage information may be inaccurate.
+    * Line execution counts may be wrong.
+
+2. Most of described functionality will be incorporated into Gradle plugin.
+
+### Usage
+
+#### TL;DR
+```bash
+kotlinc-native main.kt -Xcoverage
+./program.kexe
+llvm-profdata merge program.kexe.profraw -o program.profdata
+llvm-cov report program.kexe -instr-profile program.profdata
+```
+
+#### Compiling with coverage enabled
+
+There are 2 compiler flags that allows to generate coverage information:
+* `-Xcoverage`. Generate coverage for immediate sources.
+* `-Xlibrary-to-cover=<path>`. Generate coverage for specified `klib`. 
+Note that library also should be either linked via `-library/-l` compiler option or be a transitive dependency.
+
+#### Running covered executable
+
+After the execution of the compiled binary (ex. `program.kexe`) `program.kexe.profraw` will be generated.
+By default it will be generated in the same location where binary was created. The are two ways to override this behavior:
+ * `-Xcoverage-file=<path>` compiler flag.
+ * `LLVM_PROFILE_FILE` environment variable. So if you run your program like this:
+```
+LLVM_PROFILE_FILE=build/program.profraw ./program.kexe
+```
+Then the coverage information will be stored to the `build` dir as `program.profraw`.
+
+#### Parsing `*.profraw` 
+
+Generated file can be parsed with `llvm-profdata` utility. Basic usage:  
+```
+llvm-profdata merge default.profraw -o program.profdata
+```  
+See [command guide](http://llvm.org/docs/CommandGuide/llvm-profdata.html) for more options.
+
+#### Creating reports
+
+The last step is to create a report from the `program.profdata` file. 
+It can be done with `llvm-cov` utility (refer to [command guide](http://llvm.org/docs/CommandGuide/llvm-cov.html) for detailed usage).
+For example, we can see a basic report using:  
+```
+llvm-cov report program.kexe -instr-profile program.profdata
+``` 
+Or show a line-by-line coverage information in html:  
+```
+llvm-cov show program.kexe -instr-profile program.profdata  -format=html > report.html
+```
+
+### Sample
+Usually coverage information is collected during running of the tests. 
+Please refer to `samples/coverage` to see how it can be done.
+
+
+### Useful links
+* [LLVM Code Coverage Mapping Format](https://llvm.org/docs/CoverageMappingFormat.html)