QL packs are used to organize the files used in CodeQL analysis. They contain queries, library files, query suites, and important metadata.

The CodeQL repository contains QL packs for C/C++, C#, Java, JavaScript, Python, and Ruby. The CodeQL for Go repository contains a QL pack for Go analysis. You can also make custom QL packs to contain your own queries and libraries.

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 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.

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.

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 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.

qlpack.yml
mycompany/
  java/
    security/
      CustomSinks.qll
Security/
CustomQuery.ql

For more information, see ":ref:`Importing modules <importing-modules>`" in the QL language reference.

The following properties are supported in qlpack.yml files.

dependencies:
  codeql/cpp-all: ^0.0.2

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. Save files for queries and tests in separate packs and, where possible, organize custom packs into specific folders for each target language.

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 their name only, rather than their full path. For more information about query suites, see ":doc:`Creating CodeQL query suites <creating-codeql-query-suites>`."

For example, a qlpack.yml file for a QL pack featuring custom C++ queries and libraries may contain:

name: my-custom-queries
version: 0.0.0
libraryPathDependencies: codeql/cpp-all
suites: my-custom-suites

where codeql/cpp-all is the name of the QL pack for C/C++ analysis included in the CodeQL repository.

Note

When you create a custom QL pack, it's usually a good idea to add it to the search path in your CodeQL configuration. This will ensure that any libraries the pack contains are available to the CodeQL CLI. For more information, see ":ref:`Specifying command options in a CodeQL configuration file <specifying-command-options-in-a-codeql-configuration-file>`."

For custom QL packs containing test files, you also need to include an extractor property so that the test run command knows how to create test databases. You may also wish to specify the tests property.

For more information about running tests, see ":doc:`Testing custom queries <testing-custom-queries>`."

Each of the languages in the CodeQL repository has four main QL packs:

• Core library pack for the language, with the :ref:`database schema <codeql-database-schema>` used by the language, and CodeQL libraries, and queries at ql/<language>/ql/lib
• Core query pack for the language that includes the default queries for the language, along with their query suites at ql/<language>/ql/src
• Tests for the core language libraries and queries at ql/<language>/ql/test
• Upgrade scripts for the language at ql/<language>/upgrades

The qlpack.yml file for a core library pack uses the following properties: name, version, dbscheme. The dbscheme property should only be defined in the core QL pack for a language.

For example, the qlpack.yml file for C/C++ analysis libraries contains:

name: codeql/cpp-all
version: 0.0.0
dbscheme: semmlecode.cpp.dbscheme
dependencies:
 codeql/cpp-upgrades: "*"

The qlpack.yml file for a core query pack uses the following properties: name, version, suites, defaultSuiteFile, dependencies .

For example, the qlpack.yml file for C/C++ analysis queries contains:

name: codeql/cpp-queries
version: 0.0.0
suites: codeql-suites
defaultSuiteFile: codeql-suites/cpp-code-scanning.qls
dependencies:
 codeql/cpp-all: "*"
 codeql/suite-helpers: "*"

The qlpack.yml file for the tests for the core QL packs use the following properties: name, version, and dependencies. The dependencies always specifies the core QL pack.

For example, the qlpack.yml file for C/C++ analysis tests contains:

name: codeql/cpp-tests
version: 0.0.0
dependencies:
 codeql/cpp-all: "*"
 codeql/cpp-queries: "*"

The qlpack.yml file for a QL pack that contains only upgrade scripts uses the following properties: name and upgrades.

For example, the qlpack.yml file for C/C++ upgrades contains:

name: codeql/cpp-upgrades
upgrades: .