diff --git a/docs/codeql/codeql-cli/creating-codeql-databases.rst b/docs/codeql/codeql-cli/creating-codeql-databases.rst index b305c6e1cb6..326f260fc70 100644 --- a/docs/codeql/codeql-cli/creating-codeql-databases.rst +++ b/docs/codeql/codeql-cli/creating-codeql-databases.rst @@ -168,7 +168,9 @@ generate a database, therefore the build method must be available to the CLI. Detecting the build system ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The CodeQL CLI includes autobuilders for C/C++, C#, Go, and Java code. CodeQL +.. include:: ../reusables/kotlin-beta-note.rst + +The CodeQL CLI includes autobuilders for C/C++, C#, Go, Java and Kotlin code. CodeQL autobuilders allow you to build projects for compiled languages without specifying any build commands. When an autobuilder is invoked, CodeQL examines the source for evidence of a build system and attempts to run the optimal set of diff --git a/docs/codeql/codeql-for-visual-studio-code/working-with-codeql-packs-in-visual-studio-code.rst b/docs/codeql/codeql-for-visual-studio-code/working-with-codeql-packs-in-visual-studio-code.rst index a13832239dc..65cf1ef78ef 100644 --- a/docs/codeql/codeql-for-visual-studio-code/working-with-codeql-packs-in-visual-studio-code.rst +++ b/docs/codeql/codeql-for-visual-studio-code/working-with-codeql-packs-in-visual-studio-code.rst @@ -30,7 +30,7 @@ You can then use the CodeQL CLI to publish your pack to share with others. For m Viewing CodeQL packs and their dependencies in Visual Studio Code ----------------------------------------------------------------- To download a CodeQL pack that someone else has created, run the **CodeQL: Download Packs** command from the Command Palette. -You can download all the core CodeQL query packs, or enter the full name of a specific pack to download. For example, to download the core queries for analyzing Java, enter ``codeql/java-queries``. +You can download all the core CodeQL query packs, or enter the full name of a specific pack to download. For example, to download the core queries for analyzing Java or Kotlin, enter ``codeql/java-queries``. Whether you have downloaded a CodeQL pack or created your own, you can open the ``qlpack.yml`` file in the root of a CodeQL pack directory in Visual Studio Code and view the dependencies section to see what libraries the pack depends on. diff --git a/docs/codeql/codeql-language-guides/abstract-syntax-tree-classes-for-working-with-java-programs.rst b/docs/codeql/codeql-language-guides/abstract-syntax-tree-classes-for-working-with-java-programs.rst index 83bce3652b9..7819f762b98 100644 --- a/docs/codeql/codeql-language-guides/abstract-syntax-tree-classes-for-working-with-java-programs.rst +++ b/docs/codeql/codeql-language-guides/abstract-syntax-tree-classes-for-working-with-java-programs.rst @@ -7,6 +7,8 @@ CodeQL has a large selection of classes for representing the abstract syntax tre .. include:: ../reusables/abstract-syntax-tree.rst +.. include:: ../reusables/kotlin-java-differences.rst + Statement classes ----------------- diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-java.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-java.rst index 75309842ad5..cd64a18bcad 100644 --- a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-java.rst +++ b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-java.rst @@ -5,6 +5,8 @@ Analyzing data flow in Java You can use CodeQL to track the flow of data through a Java program to its use. +.. include:: ../reusables/kotlin-java-differences.rst + About this article ------------------ diff --git a/docs/codeql/codeql-language-guides/codeql-for-java.rst b/docs/codeql/codeql-language-guides/codeql-for-java.rst index 53489bc5207..6a16ea0658d 100644 --- a/docs/codeql/codeql-language-guides/codeql-for-java.rst +++ b/docs/codeql/codeql-language-guides/codeql-for-java.rst @@ -1,9 +1,17 @@ .. _codeql-for-java: -CodeQL for Java -=============== +CodeQL for Java and Kotlin +========================== -Experiment and learn how to write effective and efficient queries for CodeQL databases generated from Java codebases. +Experiment and learn how to write effective and efficient queries for CodeQL databases generated from Java and Kotlin codebases. + +.. include:: ../reusables/kotlin-beta-note.rst + +.. include:: ../reusables/kotlin-java-differences.rst + +.. pull-quote:: Enabling Kotlin support + + To enable Kotlin support, you should enable `java` as a language. .. toctree:: :hidden: diff --git a/docs/codeql/codeql-overview/system-requirements.rst b/docs/codeql/codeql-overview/system-requirements.rst index 5569462e5ae..fd4465f9ba4 100644 --- a/docs/codeql/codeql-overview/system-requirements.rst +++ b/docs/codeql/codeql-overview/system-requirements.rst @@ -11,6 +11,8 @@ Supported platforms ####################### .. include:: ../support/reusables/platforms.rst + +.. include:: ../reusables/kotlin-beta-note.rst Additional software requirements ################################ diff --git a/docs/codeql/query-help/codeql-cwe-coverage.rst b/docs/codeql/query-help/codeql-cwe-coverage.rst index c0b36646df8..680f41b1056 100644 --- a/docs/codeql/query-help/codeql-cwe-coverage.rst +++ b/docs/codeql/query-help/codeql-cwe-coverage.rst @@ -3,6 +3,8 @@ CodeQL CWE coverage You can view the full coverage of MITRE's Common Weakness Enumeration (CWE) or coverage by language for the latest release of CodeQL. +.. include:: ../reusables/kotlin-beta-note.rst + About CWEs ########## diff --git a/docs/codeql/query-help/index.rst b/docs/codeql/query-help/index.rst index b45b3a5bf87..6dad02ce2b1 100644 --- a/docs/codeql/query-help/index.rst +++ b/docs/codeql/query-help/index.rst @@ -6,11 +6,13 @@ View the query help for the queries included in the ``code-scanning``, ``securit - :doc:`CodeQL query help for C and C++ ` - :doc:`CodeQL query help for C# ` - :doc:`CodeQL query help for Go ` -- :doc:`CodeQL query help for Java ` +- :doc:`CodeQL query help for Java and Kotlin ` - :doc:`CodeQL query help for JavaScript ` - :doc:`CodeQL query help for Python ` - :doc:`CodeQL query help for Ruby ` +.. include:: ../reusables/kotlin-beta-note.rst + .. pull-quote:: Information Each query help article includes: diff --git a/docs/codeql/reusables/extractors.rst b/docs/codeql/reusables/extractors.rst index a3a4952811d..606c57d0208 100644 --- a/docs/codeql/reusables/extractors.rst +++ b/docs/codeql/reusables/extractors.rst @@ -10,7 +10,7 @@ - ``csharp`` * - Go - ``go`` - * - Java + * - Java/Kotlin - ``java`` * - JavaScript/TypeScript - ``javascript`` diff --git a/docs/codeql/reusables/kotlin-beta-note.rst b/docs/codeql/reusables/kotlin-beta-note.rst new file mode 100644 index 00000000000..d05d137a13e --- /dev/null +++ b/docs/codeql/reusables/kotlin-beta-note.rst @@ -0,0 +1,4 @@ + .. pull-quote:: Note + + CodeQL analysis for Kotlin is currently in beta. During the beta, analysis of Kotlin code, + and the accompanying documentation, will not be as comprehensive as for other languages. \ No newline at end of file diff --git a/docs/codeql/reusables/kotlin-java-differences.rst b/docs/codeql/reusables/kotlin-java-differences.rst new file mode 100644 index 00000000000..b9d792d6d9f --- /dev/null +++ b/docs/codeql/reusables/kotlin-java-differences.rst @@ -0,0 +1,18 @@ +Writing CodeQL queries in Kotlin versus Java +-------------------------------------------- + +When writing Kotlin-specific elements (such as a `WhenExpr`) you’ll need to use Kotlin-specific CodeQL classes, but writing queries for Kotlin and Java is largely the same. The two make use of the same libraries such as DataFlow, TaintTracking, or SSA, and the same classes such as `MethodAccess` or `Class`. + +There are however some important cases where writing queries for Kotlin can produce surprising results compared to writing Java queries, as CodeQL works with the JVM bytecode representation of the source code. + +Be careful when trying to model code elements that don’t exist in Java, such as `NotNullExpr (expr!!)`, because they could interact in unexpected ways with common predicates. For example, `MethodAccess.getQualifier()` gets a `NotNullExpr `instead of a `VarAccess`` in the following Kotlin code: + +`someVar!!.someMethodCall()` + +In that specific case, you can use the predicate `Expr.getUnderlyingExpr()`. This goes directly to the underlying `VarAccess`` to produce a more similar behavior to that in Java. + +Nullable elements (`?`) can also produce unexpected behavior. To avoid a `NullPointerException`, Kotlin may inline calls like `expr.toString()` to `String.valueOf(expr)` when `expr` is nullable. Make sure that you write CodeQL around the extracted code, and do not directly modify the source code in the codebase. + +Another example is that if-else expressions are translated into `WhenExprs` in CodeQL, instead of the more typical `IfStmt` in Java. + +In general, you can debug these issues with the AST (you can use the `CodeQL: View AST`` command from Visual Studio Code’s CodeQL extension, or run the `PrintAst.ql`` query) and checking what exactly CodeQL is extracting from your code. \ No newline at end of file diff --git a/docs/codeql/support/reusables/frameworks.rst b/docs/codeql/support/reusables/frameworks.rst index b83b26f486a..191b40b4896 100644 --- a/docs/codeql/support/reusables/frameworks.rst +++ b/docs/codeql/support/reusables/frameworks.rst @@ -93,9 +93,11 @@ and the CodeQL library pack ``codeql/go-all`` (`changelog `_, Serialization `zap `_, Logging library -Java built-in support +Java and Kotlin built-in support ================================== +.. include:: ../reusables/kotlin-beta-note.rst + Provided by the current versions of the CodeQL query pack ``codeql/java-queries`` (`changelog `__, `source `__) and the CodeQL library pack ``codeql/java-all`` (`changelog `__, `source `__).