hohn/codeql
1
0
Fork 0
mirror of https://github.com/github/codeql.git synced 2026-04-22 07:15:15 +02:00
Code Issues Packages Projects Releases Wiki Activity

Apply suggestions from code review

Browse Source 
Co-authored-by: Shati Patel <42641846+shati-patel@users.noreply.github.com>
This commit is contained in:
Henning Makholm
2020-05-14 23:13:50 +02:00
committed by GitHub
parent 69ba22a3c2
commit 43e8a0f716
1 changed files with 28 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
docs/language/ql-handbook/language.rst
View File

@@ -45,13 +45,13 @@ For a QL program to be *valid*, it must conform to a variety of conditions that
Library path
------------
The library path an ordered list of directory locations that is used
in for resolving module imports, described below. It is not strictly
The library path is an ordered list of directory locations. It is used
for resolving module imports (see `Module resolution <#module-resolution>`__)). The library path is not strictly
speaking a core part of the QL language, since different
implementations of QL construct it in slightly different ways. Most QL
tooling also allows specifying it explicitly on the command line for a
tools also allow you to explicitly specify the library path on the command line for a
particular invocation, though that is that is rarely done, and only
useful in very special situation. This section describes the default
useful in very special situations. This section describes the default
construction of the library path.
First, determine the *query directory* of the ``.ql`` file being
@@ -63,56 +63,56 @@ directory, the directory of the ``.ql`` file itself is the query
directory.
A ``queries.xml`` file that defines a query directory must always
contain, containing a single top-level tag named
contain a single top-level tag named
``queries``, which has a ``language`` attribute set to the identifier
of the active database scheme (for example, ``<queries
of the active database schema (for example, ``<queries
language="java"/>``).
A ``qlpack.yml`` file defines a `QL pack
<https://help.semmle.com/codeql/codeql-cli/reference/qlpack-overview.html>`;
its content is described in the CodeQL CLI documentation. This file
will not be recognized when using older QL tooling that is not based
on the CodeQL CLI (that is, LGTM.com, LGTM Enterprise, Odasa, QL for
Eclipse, and QL for Visual Studio).
<https://help.semmle.com/codeql/codeql-cli/reference/qlpack-overview.html>`__.
The content of a ``qlpack.yml`` file is described in the CodeQL CLI documentation. This file
will not be recognized when using legacy tools that are not based
on the CodeQL CLI (that is, LGTM.com, LGTM Enterprise, ODASA, CodeQL for
Eclipse, and CodeQL for Visual Studio).
If both a ``queries.xml`` and a ``qlpack.yml`` exist in the same
directory the latter takes precedence (and the former is assumed to
directory, the latter takes precedence (and the former is assumed to
exist for compatibility with older tooling).
The query directory itself becomes the first element of the library
path.
In old tooling that doesn't recognize ``qlpack.yml``, the default
value of the rest of the library path is hard-coded in the tooling for
each supporting language. It contains directories within the Odasa
In legacy QL tools that don't recognize ``qlpack.yml`` files, the default
value of the rest of the library path for
each supported language is hard-coded. The tools contain directories within the ODASA
distribution that define the default CodeQL libraries for the selected
language. Which language to use depends on the ``language`` attibute
language. Which language to use depends on the ``language`` attribute
of the ``queries.xml`` file if not overridden with a ``--language``
option to Odasa.
option to the ODASA CLI.
On the other hand, the CodeQL CLI and newer tooling based on it (e.g.,
GitHub Code Scanning and the Visual Stidio Code extension for CodeQL)
constructs a default library path using QL packs. For each QL pack
added to the language path, the QL packs named in its
On the other hand, the CodeQL CLI and newer tools based on it (such as
GitHub Code Scanning and the CodeQL extension for Visual Studio Code)
construct a default library path using QL packs. For each QL pack
added to the library path, the QL packs named in its
``libraryPathDependencies`` will be subsequently added to the library
path, and the process continues until all packs have been
resolved. The actual library path consists of the root directories of
the selected QL packs. This process depends on a mechanism for finding
QL packs by pack name, as described in the CodeQL CLI documentation.
QL packs by pack name, as described in the `CodeQL CLI documentation <https://help.semmle.com/codeql/codeql-cli.html>`__.
When the query directory contains a ``queries.xml`` file but no
``qlpack.yml``, the QL pack resolution behaves as if it defines a QL
pack with no name and a single library-path dependency named
pack with no name and a single library path dependency named
``legacy-libraries-LANGUAGE`` where ``LANGUAGE`` is taken from
``queries.xml``. The ``github/codeql`` repository provides packs with
names following this pattern, which themselves depend on the actual
CodeQL libraries for each language.
When the query directory contains neither ``queries.xml`` nor
``qlpack.yml`` it will be considered to be a QL pack with no name and
When the query directory contains neither a ``queries.xml`` nor
``qlpack.yml`` file, it is considered to be a QL pack with no name and
no library dependencies. This causes the library path to consist of
*only* the query directory itself, which is not generally useful --
but will suffice to run toy examples of QL code that don't actually
*only* the query directory itself. This is not generally useful,
but it suffices for running toy examples of QL code that don't
use information from the database.
Name resolution
@@ -237,7 +237,7 @@ For qualified identifiers (``a.b``):
- Build up a list of *candidate search paths*, consisting of the
current file's directory, and each of the directories on the
*library path* (in order).
`library path <#library-path>`__ (in order).
- Determine the first candidate search path that has a *matching* QLL file for the import directive's qualified name. A QLL file in a candidate search path is said to match a qualified name if, starting from the candidate search path, there is a subdirectory for each successive qualifier in the qualified name, and the directory named by the final qualifier contains a file whose base name matches the qualified name's base name, with the addition of the file extension ``.qll``. The file and directory names are matched case-sensitively, regardless of whether the filesystem is case-sensitive or not.