diff --git a/docs/language/global-sphinx-files/global-conf.py b/docs/language/global-sphinx-files/global-conf.py index 260783d9117..84912a8c538 100644 --- a/docs/language/global-sphinx-files/global-conf.py +++ b/docs/language/global-sphinx-files/global-conf.py @@ -56,9 +56,9 @@ def setup(sphinx): # built documents. # # The short X.Y version. -version = u'1.22' +version = u'1.22.1' # The full version, including alpha/beta/rc tags. -release = u'1.22' +release = u'1.22.1' copyright = u'2019 Semmle Ltd' author = u'Semmle Ltd' diff --git a/docs/language/learn-ql/cpp/zero-space-terminator.rst b/docs/language/learn-ql/cpp/zero-space-terminator.rst index 7026d9fa9ae..a9370f7828d 100644 --- a/docs/language/learn-ql/cpp/zero-space-terminator.rst +++ b/docs/language/learn-ql/cpp/zero-space-terminator.rst @@ -87,6 +87,10 @@ Now we can write a query using these classes: Note that there is no need to check whether anything is added to the ``strlen`` expression, as it would be in the corrected C code ``malloc(strlen(string) + 1)``. This is because the corrected code would in fact be an ``AddExpr`` containing a ``StrlenCall``, not an instance of ``StrlenCall`` itself. A side-effect of this approach is that we omit certain unlikely patterns such as ``malloc(strlen(string) + 0``). In practice we can always come back and extend our query to cover this pattern if it is a concern. +.. pull-quote:: + + Tip + For some projects, this query may not return any results. Possibly the project you are querying does not have any problems of this kind, but it is also important to make sure the query itself is working properly. One solution is to set up a test project with examples of correct and incorrect code to run the query against (the C code at the very top of this page makes a good starting point). Another approach is to test each part of the query individually to make sure everything is working. When you have defined the basic query then you can refine the query to include further coding patterns or to exclude false positives: diff --git a/docs/language/learn-ql/csharp/ql-for-csharp.rst b/docs/language/learn-ql/csharp/ql-for-csharp.rst index 013464ed036..bc5cc9e9959 100644 --- a/docs/language/learn-ql/csharp/ql-for-csharp.rst +++ b/docs/language/learn-ql/csharp/ql-for-csharp.rst @@ -20,17 +20,6 @@ These topics provide an overview of the CodeQL libraries for C# and show example - :doc:`Tutorial: Analyzing data flow in C# ` demonstrates how to write queries using the standard data flow and taint tracking libraries for C#. -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - Other resources --------------- diff --git a/docs/language/learn-ql/java/call-graph.rst b/docs/language/learn-ql/java/call-graph.rst index bb24c2d8550..cfaa33cad9f 100644 --- a/docs/language/learn-ql/java/call-graph.rst +++ b/docs/language/learn-ql/java/call-graph.rst @@ -78,6 +78,8 @@ Given this API, we can easily write a query that finds methods that are not call ➤ `See this in the query console `__. This simple query typically returns a large number of results. +.. pull-quote:: + Note We have to use ``polyCalls`` instead of ``calls`` here: we want to be reasonably sure that ``callee`` is not called, either directly or via overriding. diff --git a/docs/language/learn-ql/java/expressions-statements.rst b/docs/language/learn-ql/java/expressions-statements.rst index b08f2cf0b8b..25d605b18b8 100644 --- a/docs/language/learn-ql/java/expressions-statements.rst +++ b/docs/language/learn-ql/java/expressions-statements.rst @@ -18,6 +18,8 @@ Specifically, consider the following code snippet: If ``l`` is bigger than 2\ :sup:`31`\ - 1 (the largest positive value of type ``int``), then this loop will never terminate: ``i`` will start at zero, being incremented all the way up to 2\ :sup:`31`\ - 1, which is still smaller than ``l``. When it is incremented once more, an arithmetic overflow occurs, and ``i`` becomes -2\ :sup:`31`\, which also is smaller than ``l``! Eventually, ``i`` will reach zero again, and the cycle repeats. +.. pull-quote:: + More about overflow All primitive numeric types have a maximum value, beyond which they will wrap around to their lowest possible value (called an "overflow"). For ``int``, this maximum value is 2\ :sup:`31`\ - 1. Type ``long`` can accommodate larger values up to a maximum of 2\ :sup:`63`\ - 1. In this example, this means that ``l`` can take on a value that is higher than the maximum for type ``int``; ``i`` will never be able to reach this value, instead overflowing and returning to a low value. diff --git a/docs/language/learn-ql/java/introduce-libraries-java.rst b/docs/language/learn-ql/java/introduce-libraries-java.rst index b3d5987ab41..cf8a2f3c27c 100644 --- a/docs/language/learn-ql/java/introduce-libraries-java.rst +++ b/docs/language/learn-ql/java/introduce-libraries-java.rst @@ -14,6 +14,10 @@ The library is implemented as a set of QL modules, that is, files with the exten The rest of this topic briefly summarizes the most important classes and predicates provided by this library. +.. pull-quote:: + + Note + The example queries in this topic illustrate the types of results returned by different library classes. The results themselves are not interesting but can be used as the basis for developing a more complex query. The tutorial topics show how you can take a simple query and fine-tune it to find precisely the results you're interested in. Summary of the library classes @@ -315,7 +319,11 @@ Class ``Javadoc`` represents an entire Javadoc comment as a tree of ``JavadocEle ➤ `See this in the query console `__. None of the LGTM.com demo projects uses the ``@author`` tag on private fields. - Note that on line 5 we used ``getParent+`` to capture tags that are nested at any depth within the Javadoc comment. +.. pull-quote:: + + Note + + On line 5 we used ``getParent+`` to capture tags that are nested at any depth within the Javadoc comment. For more information on working with Javadoc, see the :doc:`tutorial on Javadoc `. @@ -369,7 +377,7 @@ Conversely, ``Callable.getAReference`` returns a ``Call`` that refers to it. So where not exists(c.getAReference()) select c -➤ `See this in the query console `__. The LGTM.com demo projects all appear to have many methods that are not called directly, but this is unlikely to be the whole story. To explore this area further, see `Navigating the call graph `__. +➤ `See this in the query console `__. The LGTM.com demo projects all appear to have many methods that are not called directly, but this is unlikely to be the whole story. To explore this area further, see :doc:`Navigating the call graph `. For more information about callables and calls, see the :doc:`call graph tutorial `. diff --git a/docs/language/learn-ql/java/types-class-hierarchy.rst b/docs/language/learn-ql/java/types-class-hierarchy.rst index 7677c64965d..a438f111cab 100644 --- a/docs/language/learn-ql/java/types-class-hierarchy.rst +++ b/docs/language/learn-ql/java/types-class-hierarchy.rst @@ -32,6 +32,8 @@ To determine ancestor types (including immediate super types, and also *their* s ➤ `See this in the query console `__. If this query were run on the example snippet above, the query would return ``A``, ``I``, and ``java.lang.Object``. +.. pull-quote:: + Tip If you want to see the location of ``B`` as well as ``A``, you can replace ``B.getASupertype+()`` with ``B.getASupertype*()`` and re-run the query. diff --git a/docs/language/learn-ql/javascript/introduce-libraries-js.rst b/docs/language/learn-ql/javascript/introduce-libraries-js.rst index edac4a8c21b..f01a8387a18 100644 --- a/docs/language/learn-ql/javascript/introduce-libraries-js.rst +++ b/docs/language/learn-ql/javascript/introduce-libraries-js.rst @@ -224,7 +224,7 @@ The `TopLevel `__. Many projects include examples of this pattern. -2. Finding 'except' blocks that do nothing -'''''''''''''''''''''''''''''''''''''''''' +2. Finding ``except`` blocks that do nothing +'''''''''''''''''''''''''''''''''''''''''''' For our second example, we can use a simplified version of a query from the standard query set. We look for all ``except`` blocks that do nothing. @@ -141,7 +141,7 @@ where ``ex`` is an ``ExceptStmt`` and ``Pass`` is the class representing ``pass` Both forms are equivalent. Using the positive expression, the whole query looks like this: -**Find pass-only ``except`` blocks** +**Find pass-only** ``except`` **blocks** .. code-block:: ql diff --git a/docs/language/learn-ql/python/pointsto-type-infer.rst b/docs/language/learn-ql/python/pointsto-type-infer.rst index eb80efe815f..7ae9368d02c 100644 --- a/docs/language/learn-ql/python/pointsto-type-infer.rst +++ b/docs/language/learn-ql/python/pointsto-type-infer.rst @@ -37,7 +37,8 @@ The predicate ``ControlFlowNode.pointsTo(...)`` shows which object a control flo predicate pointsTo(Context context, Value object, ControlFlowNode origin) ``object`` is an object that the control flow node refers to, and ``origin`` is where the object comes from, which is useful for displaying meaningful results. - The third form includes the ``context`` in which the control flow node refers to the ``object``. This form can usually be ignored. + +The third form includes the ``context`` in which the control flow node refers to the ``object``. This form can usually be ignored. .. pull-quote:: @@ -62,7 +63,7 @@ We want to find ``except`` blocks in a ``try`` statement that are in the wrong o First we can write a query to find ordered pairs of ``except`` blocks for a ``try`` statement. -**Ordered except blocks in same ``try`` statement** +**Ordered except blocks in same** ``try`` **statement** .. code-block:: ql @@ -81,7 +82,7 @@ Here ``ex1`` and ``ex2`` are both ``except`` handlers in the ``try`` statement ` The results of this query need to be filtered to return only results where ``ex1`` is more general than ``ex2``. We can use the fact that an ``except`` block is more general than another block if the class it handles is a superclass of the other. -**More general ``except`` block** +**More general** ``except`` **block** .. code-block:: ql @@ -102,7 +103,7 @@ ensures that ``cls1`` is a ``ClassValue`` that the ``except`` block would handle Combining the parts of the query we get this: -**More general ``except`` block precedes more specific** +**More general** ``except`` **block precedes more specific** .. code-block:: ql diff --git a/docs/language/learn-ql/python/statements-expressions.rst b/docs/language/learn-ql/python/statements-expressions.rst index 9a0a2484fc7..d3b4e68af6c 100644 --- a/docs/language/learn-ql/python/statements-expressions.rst +++ b/docs/language/learn-ql/python/statements-expressions.rst @@ -143,7 +143,7 @@ Python implementations commonly cache small integers and single character string We can check for these as follows: -**Find comparisons to integer or string literals using ``is``** +**Find comparisons to integer or string literals using** ``is`` .. code-block:: ql @@ -158,6 +158,8 @@ We can check for these as follows: The clause ``cmp.getOp(0) instanceof Is and cmp.getComparator(0) = literal`` checks that the first comparison operator is "is" and that the first comparator is a literal. +.. pull-quote:: + Tip We have to use ``cmp.getOp(0)`` and ``cmp.getComparator(0)``\ as there is no ``cmp.getOp()`` or ``cmp.getComparator()``. The reason for this is that a ``Compare`` expression can have multiple operators. For example, the expression ``3 < x < 7`` has two operators and two comparators. You use ``cmp.getComparator(0)`` to get the first comparator (in this example the ``3``) and ``cmp.getComparator(1)`` to get the second comparator (in this example the ``7``). @@ -253,9 +255,7 @@ checks that the value of the attribute (the expression to the left of the dot in Class and function definitions ------------------------------ -As Python is a dynamically typed language, class, and function definitions are executable statements. This means that a class statement is both a statement and a scope containing statements. To represent this cleanly the class definition is broken into a number of parts. At runtime, when a class definition is executed a class object is created and then assigned to a variable of the same name in the scope enclosing the class. This class is created from a code-object representing the source code for the body of the class. To represent this the ``ClassDef`` class (which represents a ``class`` statement) subclasses ``Assign``. The ``Class`` class, which represents the body of the class, can be accessed via the ``ClassDef.getDefinedClass()`` - -``FunctionDef``, ``Function`` are handled similarly. +As Python is a dynamically typed language, class, and function definitions are executable statements. This means that a class statement is both a statement and a scope containing statements. To represent this cleanly the class definition is broken into a number of parts. At runtime, when a class definition is executed a class object is created and then assigned to a variable of the same name in the scope enclosing the class. This class is created from a code-object representing the source code for the body of the class. To represent this the ``ClassDef`` class (which represents a ``class`` statement) subclasses ``Assign``. The ``Class`` class, which represents the body of the class, can be accessed via the ``ClassDef.getDefinedClass()``. ``FunctionDef`` and ``Function`` are handled similarly. Here is the relevant part of the class hierarchy: diff --git a/docs/language/support/conf.py b/docs/language/support/conf.py index 2e4bbf46d64..30d7b1a3028 100644 --- a/docs/language/support/conf.py +++ b/docs/language/support/conf.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# QL and LGTM support info build configuration file, created +# CodeQL and LGTM support info build configuration file, created # on Tuesday 19th February. # # This file is execfile()d with the current directory set to its diff --git a/docs/language/support/framework-support.rst b/docs/language/support/framework-support.rst index dc1995f9345..3e3cb8557af 100644 --- a/docs/language/support/framework-support.rst +++ b/docs/language/support/framework-support.rst @@ -1,7 +1,7 @@ Frameworks and libraries ######################## -The QL libraries and queries in version |version| have been explicitly checked against the libraries and frameworks listed below. +The libraries and queries in version |version| have been explicitly checked against the libraries and frameworks listed below. .. pull-quote:: diff --git a/docs/language/support/index.rst b/docs/language/support/index.rst index 5fee43da196..6236b4c1543 100644 --- a/docs/language/support/index.rst +++ b/docs/language/support/index.rst @@ -1,7 +1,7 @@ Supported languages and frameworks ################################## -These pages describe the languages and frameworks supported in the latest enterprise release of QL and LGTM. +These pages describe the languages and frameworks supported in the latest enterprise release of CodeQL and LGTM. (CodeQL was previously known as QL.) Users of `LGTM.com `_ may find that additional features are supported because it's updated more frequently. For details see: @@ -11,4 +11,4 @@ For details see: language-support.rst framework-support.rst -For details of the QL libraries, see `QL standard libraries `_. \ No newline at end of file +For details of the CodeQL libraries, see `CodeQL standard libraries `_. \ No newline at end of file diff --git a/docs/language/support/language-support.rst b/docs/language/support/language-support.rst index 9fa1e60e05d..d4b1b95ba2e 100644 --- a/docs/language/support/language-support.rst +++ b/docs/language/support/language-support.rst @@ -1,7 +1,8 @@ Languages and compilers ####################### -QL and LGTM version |version| support analysis of the following languages compiled by the following compilers. +CodeQL and LGTM version |version| support analysis of the following languages compiled by the following compilers. +(CodeQL was previously known as QL.) Note that where there are several versions or dialects of a language, the supported variants are listed. If your code requires a particular version of a compiler, check that this version is included below. diff --git a/docs/language/support/versions-compilers.csv b/docs/language/support/versions-compilers.csv index 4a59214c47f..74f69d662b6 100644 --- a/docs/language/support/versions-compilers.csv +++ b/docs/language/support/versions-compilers.csv @@ -10,6 +10,7 @@ C#,C# up to 7.3. with .NET up to 4.8 [3]_.,"Microsoft Visual Studio up to 2019, .NET Core up to 2.2","``.sln``, ``.csproj``, ``.cs``, ``.cshtml``, ``.xaml``" COBOL,ANSI 85 or newer [4]_.,Not applicable,"``.cbl``, ``.CBL``, ``.cpy``, ``.CPY``, ``.copy``, ``.COPY``" +Go (aka Golang), "Go up to 1.13", "Go 1.11 or more recent", ``.go`` Java,"Java 6 to 12 [5]_.","javac (OpenJDK and Oracle JDK), Eclipse compiler for Java (ECJ) [6]_.",``.java``