Profiling documentation. (#2599)

HACKING.md

@@ -1,3 +1,47 @@
+## Profiling the compiler
+
+### Profiling with Async profiler
+
+ IDEA Ultimate contains an Async sampling profiler.
+ As of IDEA 2018.3 Async sampling profiler is still an experimental feature, so use Ctrl-Alt-Shift-/ on Linux,
+Cmd-Alt-Shift-/ on macOS to activate it. Then start compilation in CLI with `--no-daemon` and
+`-Porg.gradle.workers.max=1` flags (running Gradle task with the profiler doesn't seem to work properly) and attach
+to the running process using "Run/Attach Profiler to Local Process" menu item.
+
+ Select "K2NativeKt" or "org.jetbrains.kotlin.cli.utilities.MainKt" process.
+On completion profiler will produce flame diagram which could be navigated with the mouse
+(click-drag moves, wheel scales). More RAM in IDE (>4G) could be helpful when analyzing longer runs.
+As Async is a sampling profiler, to get sensible coverage longer runs are important.
+
+### Profiling with YourKit
+
+Unlike Async profiler in IDEA, YourKit can work as an exact profiler and provide complete coverage
+of all methods along with exact invocation counters.
+
+Install the YourKit profiler for your platform from https://www.yourkit.com/java/profiler.
+Set AGENT variable to the JVMTI agent provided by YourKit, like
+
+        export AGENT=/Applications/YourKit-Java-Profiler-2018.04.app/Contents/Resources/bin/mac/libyjpagent.jnilib
+
+To profile standard library compilation:
+
+        ./gradlew -PstdLibJvmArgs="-agentpath:$AGENT=probe_disable=*,listen=all,tracing"  dist
+
+To profile platform libraries start build of proper target like this:
+
+        ./gradlew -PplatformLibsJvmArgs="-agentpath:$AGENT=probe_disable=*,listen=all,tracing"  ios_arm64PlatformLibs
+
+To profile standalone code compilation use:
+
+        JAVA_OPTS="-agentpath:$AGENT=probe_disable=*,listen=all,tracing" ./dist/bin/konanc file.kt
+
+Then attach to the desired application in YourKit GUI and use CPU tab to inspect CPU consuming methods.
+Saving the trace may be needed for more analysis. Adjusting `-Xmx` in `$HOME/.yjp/ui.ini` could help
+with the big traces.
+
+To perform memory profiling follow the steps above, and after attachment to the running process
+use "Start Object Allocation Recording" button. See https://www.yourkit.com/docs/java/help/allocations.jsp for more details.
+
  ## Compiler Gradle options
 
 There are several gradle flags one can use for Konan build.
@@ -50,5 +94,4 @@ and run `./gradlew update_external_tests`
 
 * **-Ptest_verbose** enables printing compiler args and other helpful information during a test execution.
 
-        ./gradlew -Ptest_verbose :backend.native:tests:mpp_optional_expectation
-
+        ./gradlew -Ptest_verbose :backend.native:tests:mpp_optional_expectation