Merge pull request #6606 from github/aeisenberg/docs

Update the docs about qlpacks

docs/codeql/codeql-cli/about-ql-packs.rst

@@ -81,7 +81,7 @@ The following properties are supported in ``qlpack.yml`` files.
      - All packs
      - A version number for this QL pack. This must be a valid semantic version that meets the `SemVer v2.0.0 specification <https://semver.org/spec/v2.0.0.html>`__.
    * - ``libraryPathDependencies``
-     - ``codeql-javascript``
+     - ``codeql/javascript-all``
      - Optional
      - The names of any QL packs that this QL pack depends on, as a sequence. This gives the pack access to any libraries, database schema, and query suites defined in the dependency.
    * - ``suites``
@@ -104,7 +104,18 @@ The following properties are supported in ``qlpack.yml`` files.
      - ``.``
      - Packs with upgrades
      - The path to a directory within the pack that contains upgrade scripts, defined relative to the pack directory. The ``database upgrade`` action uses these scripts to update databases that were created by an older version of an extractor so they're compatible with the current extractor (see `Upgrade scripts for a language <#upgrade-scripts-for-a-language>`__ below.)
+   * - ``dependencies``
+     - .. code-block:: yaml
 
+          dependencies:
+            codeql/cpp-all: ^0.0.2
+
+     - Packs that define CodeQL package dependencies on other packs
+     - A map from pack references to the semantic version range that is compatible with this pack. Supported from CLI version v2.6.0 and onwards.
+   * - ``defaultSuiteFile``
+     - ``defaultSuiteFile: cpp-code-scanning.qls``
+     - Packs that export a set of default queries to run
+     - The path to a query suite file containing all of the queries that are run by default when this pack is passed to the ``codeql database analyze`` command. Supported from CLI version v2.6.0 and onwards.
 
 .. _custom-ql-packs:
 
@@ -138,7 +149,7 @@ and libraries may contain:
    libraryPathDependencies: codeql/cpp-all
    suites: my-custom-suites
 
-where ``codeql-cpp`` is the name of the QL pack for C/C++ analysis included in
+where ``codeql/cpp-all`` is the name of the QL pack for C/C++ analysis included in
 the CodeQL repository.
 
 .. pull-quote::
@@ -166,38 +177,61 @@ For more information about running tests, see ":doc:`Testing custom queries
 Examples of QL packs in the CodeQL repository
 ---------------------------------------------
 
-Each of the languages in the CodeQL repository has three main QL packs:
+Each of the languages in the CodeQL repository has four main QL packs:
 
-- Core QL pack for the language, with the :ref:`database schema <codeql-database-schema>`
-  used by the language, CodeQL libraries, and queries at ``ql/<language>/ql/src``
-- Tests for the core language libraries and queries pack at ``ql/<language>/ql/test``
+- 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``
 
-Core QL pack
-~~~~~~~~~~~~
+Core library pack
+~~~~~~~~~~~~~~~~~
 
-The ``qlpack.yml`` file for a core QL pack uses the following properties:
-``name``, ``version``, ``dbscheme``, and ``suites``.
+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
-<https://github.com/github/codeql/blob/main/cpp/ql/src/qlpack.yml>`__
+For example, the ``qlpack.yml`` file for `C/C++ analysis libraries
+<https://github.com/github/codeql/blob/main/cpp/ql/lib/qlpack.yml>`__
 contains:
 
 .. code-block:: yaml
 
-   name: codeql-cpp
+   name: codeql/cpp-all
    version: 0.0.0
    dbscheme: semmlecode.cpp.dbscheme
+   dependencies:
+    codeql/cpp-upgrades: "*"
+
+Core query pack
+~~~~~~~~~~~~~~~
+
+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
+<https://github.com/github/codeql/blob/main/cpp/ql/lib/qlpack.yml>`__
+contains:
+
+.. code-block:: yaml
+
+   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: "*"
 
 Tests for the core QL pack
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``qlpack.yml`` file for the tests for the core QL packs use the following
-properties: ``name``, ``version``, and ``libraryPathDependencies``.
-The ``libraryPathDependencies`` always specifies the core QL pack.
+properties: ``name``, ``version``, and ``dependencies``.
+The ``dependencies`` always specifies the core QL pack.
 
 For example, the ``qlpack.yml`` file for `C/C++ analysis tests
 <https://github.com/github/codeql/blob/main/cpp/ql/test/qlpack.yml>`__
@@ -205,15 +239,12 @@ contains:
 
 .. code-block:: yaml
 
-   name: codeql-cpp-tests
+   name: codeql/cpp-tests
    version: 0.0.0
-   libraryPathDependencies: codeql/cpp-all
+   dependencies:
+    codeql/cpp-all: "*"
+    codeql/cpp-queries: "*"
 
-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.
-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.
 
 .. _upgrade-ql-packs:
 
@@ -229,5 +260,5 @@ contains:
 
 .. code-block:: yaml
 
-   name: codeql-cpp-upgrades
+   name: codeql/cpp-upgrades
    upgrades: .