Add instruction how to run binary compatibility validator, share run configuration with its tests

libraries/.gitignore

@@ -1,5 +1,6 @@
 target
 /doc/
-.idea
+.idea/
+!.idea/runConfigurations
 *.iml
 *.ipr

libraries/.idea/runConfigurations/Binary_compatibility_tests__overwrite_results.xml

@@ -0,0 +1,23 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Binary compatibility tests, overwrite results" type="JUnit" factoryName="JUnit">
+    <extension name="coverage" enabled="false" merge="false" sample_coverage="true" runner="idea" />
+    <module name="binary-compatibility-validator" />
+    <option name="ALTERNATIVE_JRE_PATH_ENABLED" value="false" />
+    <option name="ALTERNATIVE_JRE_PATH" />
+    <option name="PACKAGE_NAME" value="" />
+    <option name="MAIN_CLASS_NAME" value="" />
+    <option name="METHOD_NAME" value="" />
+    <option name="TEST_OBJECT" value="package" />
+    <option name="VM_PARAMETERS" value="-ea -Doverwrite.output=true" />
+    <option name="PARAMETERS" value="" />
+    <option name="WORKING_DIRECTORY" value="file://$MODULE_DIR$" />
+    <option name="ENV_VARIABLES" />
+    <option name="PASS_PARENT_ENVS" value="true" />
+    <option name="TEST_SEARCH_SCOPE">
+      <value defaultName="singleModule" />
+    </option>
+    <envs />
+    <patterns />
+    <method />
+  </configuration>
+</component>

libraries/tools/binary-compatibility-validator/ReadMe.md

@@ -1,7 +1,20 @@
 # Kotlin Public API binary compatibility validation tool
 
 This tool allows to dump binary API of a Kotlin library that is public in sense of Kotlin visibilities
-and ensure that the binary API wasn't changed in a way that make this change binary incompatible.
+and ensure that the public binary API wasn't changed in a way that make this change binary incompatible.
+
+## How to run
+
+Compile and run tests. `CasesPublicAPITest` verifies the tool itself, 
+and `RuntimePublicAPITest` dumps the public API of `kotlin-runtime` and `kotlin-stdlib` jars, 
+which must be built beforehand with maven. 
+
+When substantial changes are made to the public API, it may be convenient to overwrite 
+the entire dump and compare changes later before commiting: pass `-Doverwrite.output=true` 
+property to the test to do so. 
+
+Also you can use shared run configuration "Binary compatibility tests", which also 
+overwrites the results when they differ.
 
 ## What constitutes the public API