mirror of
https://github.com/github/codeql.git
synced 2026-02-10 12:11:07 +01:00
Packaging: Refactor the cpp libraries
This PR separates the core cpp packs into `codeql/cpp-queries` and `codeql/cpp-all`. There are very few lines of code changed. Almost all changes are moving files around.
This commit is contained in:
Andrew Eisenberg
@@ -4,7 +4,7 @@ About QL packs
|
||||
==============
|
||||
|
||||
QL packs are used to organize the files used in CodeQL analysis. They
|
||||
contain queries, library files, query suites, and important metadata.
|
||||
contain queries, library files, query suites, and important metadata.
|
||||
|
||||
The `CodeQL repository <https://github.com/github/codeql>`__ contains QL packs for
|
||||
C/C++, C#, Java, JavaScript, and Python. The `CodeQL for Go
|
||||
@@ -15,15 +15,15 @@ libraries.
|
||||
QL pack structure
|
||||
-----------------
|
||||
|
||||
A QL pack must contain a file called ``qlpack.yml`` in its root directory. The other
|
||||
files and directories within the pack should be logically organized. For example, typically:
|
||||
A QL pack must contain a file called ``qlpack.yml`` in its root directory. The other
|
||||
files and directories within the pack should be logically organized. For example, typically:
|
||||
|
||||
- Queries are organized into directories for specific categories.
|
||||
- Queries for specific products, libraries, and frameworks are organized into
|
||||
- Queries for specific products, libraries, and frameworks are organized into
|
||||
their own top-level directories.
|
||||
- There is a top-level directory named ``<owner>/<language>`` for query library
|
||||
(``.qll``) files. Within this directory, ``.qll`` files should be organized into
|
||||
subdirectories for specific categories.
|
||||
- There is a top-level directory named ``<owner>/<language>`` for query library
|
||||
(``.qll``) files. Within this directory, ``.qll`` files should be organized into
|
||||
subdirectories for specific categories.
|
||||
|
||||
About ``qlpack.yml`` files
|
||||
--------------------------
|
||||
@@ -31,18 +31,18 @@ About ``qlpack.yml`` files
|
||||
When executing commands, CodeQL scans siblings of the installation directory (and
|
||||
their subdirectories) for ``qlpack.yml`` files. The metadata in the file tells
|
||||
CodeQL how to compile queries, what libraries the pack depends on, and where to
|
||||
find query suite definitions.
|
||||
find query suite definitions.
|
||||
|
||||
The content of the QL pack (queries and libraries used in CodeQL analysis) is
|
||||
The content of the QL pack (queries and libraries used in CodeQL analysis) is
|
||||
included in the same directory as ``qlpack.yml``, or its subdirectories.
|
||||
|
||||
The location of ``qlpack.yml`` defines the library path for the content
|
||||
of the QL pack. That is, for all ``.ql`` and ``.qll`` files in the QL pack,
|
||||
CodeQL will resolve all import statements relative to the ``qlpack.yml`` at the
|
||||
The location of ``qlpack.yml`` defines the library path for the content
|
||||
of the QL pack. That is, for all ``.ql`` and ``.qll`` files in the QL pack,
|
||||
CodeQL will resolve all import statements relative to the ``qlpack.yml`` at the
|
||||
pack's root.
|
||||
|
||||
For example, in a QL pack with the following contents, you can import ``CustomSinks.qll``
|
||||
from any location in the pack by declaring ``import mycompany.java.CustomSinks``.
|
||||
from any location in the pack by declaring ``import mycompany.java.CustomSinks``.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@@ -54,7 +54,7 @@ from any location in the pack by declaring ``import mycompany.java.CustomSinks``
|
||||
Security/
|
||||
CustomQuery.ql
|
||||
|
||||
For more information, see ":ref:`Importing modules <importing-modules>`"
|
||||
For more information, see ":ref:`Importing modules <importing-modules>`"
|
||||
in the QL language reference.
|
||||
|
||||
.. _qlpack-yml-properties:
|
||||
@@ -113,9 +113,9 @@ Examples of custom QL packs
|
||||
|
||||
When you write custom queries or tests, you should save them in
|
||||
custom QL packs. For simplicity, try to organize each pack logically. For more
|
||||
information, see `QL pack structure <#ql-pack-structure>`__. Save files for queries
|
||||
and tests in separate packs and, where possible, organize custom packs into specific
|
||||
folders for each target language.
|
||||
information, see `QL pack structure <#ql-pack-structure>`__. Save files for queries
|
||||
and tests in separate packs and, where possible, organize custom packs into specific
|
||||
folders for each target language.
|
||||
|
||||
QL packs for custom queries
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@@ -123,8 +123,8 @@ QL packs for custom queries
|
||||
A custom QL pack for queries must include a ``qlpack.yml`` file at
|
||||
the pack root, containing ``name``, ``version``,
|
||||
and ``libraryPathDependencies`` properties. If the pack contains query suites, you can
|
||||
use the ``suites`` property to define their location. Query suites defined
|
||||
here are called "well-known" suites, and can be used on the command line by referring to
|
||||
use the ``suites`` property to define their location. Query suites defined
|
||||
here are called "well-known" suites, and can be used on the command line by referring to
|
||||
their name only, rather than their full path.
|
||||
For more information about query suites, see ":doc:`Creating CodeQL query suites <creating-codeql-query-suites>`."
|
||||
|
||||
@@ -135,11 +135,11 @@ and libraries may contain:
|
||||
|
||||
name: my-custom-queries
|
||||
version: 0.0.0
|
||||
libraryPathDependencies: codeql-cpp
|
||||
libraryPathDependencies: codeql/cpp-all
|
||||
suites: my-custom-suites
|
||||
|
||||
where ``codeql-cpp`` is the name of the QL pack for C/C++ analysis included in
|
||||
the CodeQL repository.
|
||||
the CodeQL repository.
|
||||
|
||||
.. pull-quote::
|
||||
|
||||
@@ -207,13 +207,13 @@ contains:
|
||||
|
||||
name: codeql-cpp-tests
|
||||
version: 0.0.0
|
||||
libraryPathDependencies: codeql-cpp
|
||||
libraryPathDependencies: codeql/cpp-all
|
||||
|
||||
Notice that, unlike the example QL pack for custom tests, this file does not define
|
||||
an ``extractor`` or ``tests`` property. These properties have been added to
|
||||
the QL pack file since the release of CodeQL CLI 2.0.1.
|
||||
the QL pack file since the release of CodeQL CLI 2.0.1.
|
||||
They haven't been added yet to ensure compatibility for LGTM Enterprise users.
|
||||
After the next release of LGTM Enterprise, these files can be updated.
|
||||
After the next release of LGTM Enterprise, these files can be updated.
|
||||
|
||||
.. _upgrade-ql-packs:
|
||||
|
||||
|
||||
@@ -54,7 +54,7 @@ There are two ways to do this:
|
||||
* More advanced, add the CodeQL libraries and queries to an existing workspace. For more information, see ":ref:`Updating an existing workspace for CodeQL <existing-workspace>`" below.
|
||||
|
||||
.. pull-quote:: Note
|
||||
|
||||
|
||||
For CLI users there is a third option: If you have followed the instructions in ":ref:`Getting started with the CodeQL CLI <getting-started-with-the-codeql-cli>`" to create a CodeQL directory (for example ``codeql-home``) containing the CodeQL libraries, you can open this directory in VS Code. This also gives the extension access to the CodeQL libraries.
|
||||
|
||||
.. container:: toggle
|
||||
@@ -65,11 +65,11 @@ There are two ways to do this:
|
||||
|
||||
Your local version of the CodeQL queries and libraries should match your version of LGTM Enterprise. For example, if you
|
||||
use LGTM Enterprise 1.27, then you should clone the ``1.27.0`` branch of the `starter workspace <https://github.com/github/vscode-codeql-starter/>`__ (or the appropriate ``1.27.x`` branch, corresponding to each maintenance release).
|
||||
|
||||
|
||||
This ensures that the queries and libraries you write in VS Code also work in the query console on LGTM Enterprise.
|
||||
|
||||
If you prefer to add the CodeQL queries and libraries to an :ref:`existing workspace <existing-workspace>` instead of the starter workspace, then you should
|
||||
clone the appropriate branch of the `general CodeQL repository <https://github.com/github/codeql>`__ and the
|
||||
clone the appropriate branch of the `general CodeQL repository <https://github.com/github/codeql>`__ and the
|
||||
`CodeQL repository for Go <https://github.com/github/codeql-go>`__ and add them to your workspace.
|
||||
|
||||
.. _starter-workspace:
|
||||
@@ -94,7 +94,7 @@ To use the starter workspace:
|
||||
|
||||
Updating an existing workspace for CodeQL
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
You can add the CodeQL libraries to an existing workspace by making a local clone of the CodeQL repository directly: https://github.com/github/codeql.
|
||||
You can add the CodeQL libraries to an existing workspace by making a local clone of the CodeQL repository directly: https://github.com/github/codeql.
|
||||
|
||||
To make the standard libraries available in your workspace:
|
||||
|
||||
@@ -110,7 +110,7 @@ For example, to make a custom CodeQL folder called ``my-custom-cpp-pack`` depend
|
||||
|
||||
name: my-custom-cpp-pack
|
||||
version: 0.0.0
|
||||
libraryPathDependencies: codeql-cpp
|
||||
libraryPathDependencies: codeql/cpp-all
|
||||
|
||||
For more information about why you need to add a ``qlpack.yml`` file, see ":ref:`About QL packs <about-ql-packs>`."
|
||||
|
||||
|
||||
Reference in New Issue
Block a user