Skip to content

QL handbook: Update process for module resolution #3714

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 15, 2020
Merged

QL handbook: Update process for module resolution #3714

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3dd5290
QL reference: Update process for name resolution
shati-patel Jun 15, 2020
e69c946
Mention `libraryPathDependencies`
shati-patel Jun 15, 2020
947ccb0
Update docs/language/ql-handbook/name-resolution.rst
shati-patel Jun 15, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 8 additions & 16 deletions docs/language/ql-handbook/name-resolution.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,31 +61,23 @@ following import statement::

import examples.security.MyLibrary

To find the precise location of this library module, the QL compiler processes the import
To find the precise location of this :ref:`library module <library-modules>`, the QL compiler processes the import
statement as follows:

#. The ``.``\ s in the qualified reference correspond to file path separators, so it first looks
up ``examples/security/MyLibrary.qll`` from the directory containing ``Example.ql``.

#. If that fails, it looks up ``examples/security/MyLibrary.qll`` relative to the enclosing query
directory, if any.
This query directory is a directory containing a |queries.xml file|_, and where the contents
of that file is compatible with the current database schema.
(For example, if you are querying a JavaScript database, then the |queries.xml file|_ should
contain ``<queries language="javascript"/>``.)
#. If that fails, it looks up ``examples/security/MyLibrary.qll`` relative to the query
directory, if any.
The query directory is the first enclosing directory containing a file called ``qlpack.yml``. (Or, in legacy products, a file called ``queries.xml``.)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"First" is a bit ambiguous here -- but I'm not sure how to say it better without sounding excessively technical.


#. If no file is found using the above two checks, it looks up ``examples/security/MyLibrary.qll``
relative to each library path entry. The library path depends on the environment where you
run your query, and whether you have specified any extra settings.
#. If the compiler can't find the library file using the above two checks, it looks up ``examples/security/MyLibrary.qll``
relative to each library path entry.
The library path is usually specified using the ``libraryPathDependencies`` of the ``qlpack.yml`` file, though it may also depend on the tools you use to run your query, and whether you have specified any extra settings.
For more information, see `Library path <https://help.semmle.com/QL/ql-spec/language.html#library-path>`__ in the QL language specification.

.. |queries.xml file| replace:: ``queries.xml`` file
.. _queries.xml file: https://help.semmle.com/wiki/display/SD/queries.xml+file

If the compiler cannot resolve an import statement, then it gives a compilation error.

This process is described in more detail in the section on `module resolution <https://help.semmle.com/QL/ql-spec/language.html#module-resolution>`_
in the QL language specification.

.. _selections:

Selections
Expand Down