common/lint-psi/README

IntelliJ Core, UAST and Kotlin
------------------------------

Originally, we just downloaded snapshots of intellij-core itself from
https://www.jetbrains.com/intellij-repository/releases, like this:
https://www.jetbrains.com/intellij-repository/releases/com/jetbrains/intellij/idea/intellij-core/171.4249.32/intellij-core-171.4249.32.zip

The version number here, 171.3780.107, matches the IDE used in Studio,
defined in tools/idea/build.txt

However, when we added Kotlin support, it turns out that the Kotlin
compiler itself includes large portions of intellij-core (though thanks
to shrinking it was sometimes only partial classes). Since we need
the Kotlin compiler, we just turn off shrinking in the compiler build
and then drop in the compiler jar (which contains all of intellij-core).


Updating
--------

You will need to do a custom build of both the Kotlin compiler and the Kotlin
plugin (instructions for this are elsewhere). Pay special attention to the
IntelliJ version used---Lint needs to be source-compatible with both the
IntelliJ version used in Android Studio and the IntelliJ version that we
extract here from Kotlinc.

    Current Kotlin compiler tag: v1.5.30
    Current Kotlin plugin branch: kt-211-1.5.30

The custom build differs from the normal build in the following ways:

  * We have some patches to work around bugs.

        Kotlin compiler patches: kotlin-compiler-patch.diff
        Kotlin plugin (UAST) patches: kotlin-plugin-patch.diff

    If the patches do not apply cleanly, you can use the --3way
    flag to fall back to a merge. Just be sure to update the patch file
    after resolving conflicts.

  * When building the Kotlin compiler, set -Pteamcity=false to ensure
    that shrinking is turned off for the IntelliJ dependency.

A successful build of the Kotlin plugin should produce an artifact
under out/artifacts/KotlinPluginCommunity.

Then you can run the update.xml script, giving it paths to your local
Kotlin compiler / Kotlin plugin repositories:

    ant -f update.xml -Dkotlin_compiler_repo=$MY_KOTLIN_COMPILER_REPO_ROOT -Dkotlin_plugin_repo=$MY_KOTLIN_PLUGIN_REPO_ROOT

The packaging script will extract code and update the intellij-core and uast prebuilts
in this directory. It performs a number of steps to do that, such as unbundling the
trove classes, replacing a platform icons class, etc.

Debugging
---------

To download the sources, grab the sources using the same version as the
one UAST was built from, e.g. for 193.6015.22-EAP-SNAPSHOT, use
https://www.jetbrains.com/intellij-repository/snapshots/com/jetbrains/intellij/idea/ideaIC/193.6015.22-EAP-SNAPSHOT/ideaIC-193.6015.22-EAP-SNAPSHOT-sources.jar