Skip to content

Commit b5626cb

Browse files
jf205jf205
authored
Merge pull request github#4713 from github/sd-277
[Docs] Combine non-migrated content into single project
2 parents 9a65962 + 9702326 commit b5626cb

File tree

3 files changed

+161
-1
lines changed

3 files changed

+161
-1
lines changed

‎docs/codeql/support/index.rst

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,10 @@ For details see:
1111
language-support.rst
1212
framework-support.rst
1313

14-
For details of the CodeQL libraries, see `CodeQL standard libraries <https://help.semmle.com/QL/ql-libraries.html>`_.
14+
For details of the CodeQL libraries, see `CodeQL standard libraries <https://help.semmle.com/QL/ql-libraries.html>`_.
15+
16+
.. toctree::
17+
:hidden:
18+
19+
notes-ql-users
20+
ql-training

‎docs/codeql/support/notes-ql-users.rst

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
Notes for legacy QL CLI users
2+
=============================
3+
4+
If you've previously used the QL command-line tools (``odasa``), you'll notice a
5+
few key differences when you use the new CodeQL products:
6+
7+
* "QL snapshots" are now called `CodeQL databases <https://help.semmle.com/codeql/glossary.html#codeql-database>`__.
8+
* The process of creating a CodeQL database is much simpler and more streamlined.
9+
There's no need to create ``projects`` or ``snapshots``---just check out the
10+
code and build it using the CodeQL CLI ``codeql database create`` command.
11+
* Queries are run against CodeQL databases using the CodeQL CLI ``codeql
12+
database analyze`` command.
13+
14+
For more information, see `Creating CodeQL databases
15+
<https://help.semmle.com/codeql/codeql-cli/procedures/create-codeql-database.html>`__ and
16+
`Analyzing databases with the CodeQL CLI <https://help.semmle.com/codeql/codeql-cli/procedures/analyze-codeql-database.html>`__.
17+
For detailed guidance about equivalent commands, see `Overview of common commands
18+
<#overview-of-common-commands>`__ below.
19+
20+
.. _database-compatibiilty-notes:
21+
22+
Database compatibility notes
23+
----------------------------
24+
25+
A CodeQL database created by the CodeQL CLI serves the same purpose as a QL
26+
snapshot created using ``odasa``. They both contain a code database to query and
27+
usually a source reference for results display. However, they are not identical
28+
formats and, if you use the legacy QL tools alongside the CodeQL tools, you need
29+
to be aware of the following:
30+
31+
* Existing QL snapshots, exported using the legacy CLI, can be used with the new
32+
CodeQL tools. Unzip the snapshot and treat the directory as a database. If it
33+
was built with an earlier version of the legacy CLI, you may need to upgrade
34+
the database using ``codeql database upgrade``. For more information, see the
35+
`database upgrade reference documentation
36+
<https://help.semmle.com/codeql/codeql-cli/commands/database-upgrade.html>`__.
37+
38+
* CodeQL databases are not directly compatible with CodeQL for Eclipse.
39+
However, you can "bundle" a CodeQL database into the equivalent of a QL
40+
exported snapshot by running::
41+
42+
codeql database bundle --include-uncompressed-source -o <output-zip> <codeql-database>
43+
44+
The resulting database can be imported into CodeQL for Eclipse. For more
45+
information, see the `database bundle reference documentation <https://help.semmle.com/codeql/codeql-cli/commands/database-bundle.html>`__.
46+
47+
* .. include:: ../reusables/index-files-note.rst
48+
49+
* CodeQL databases cannot be directly uploaded to an LGTM Enterprise instance.
50+
For more information, see `Preparing CodeQL databases to upload to LGTM
51+
<https://help.semmle.com/lgtm-enterprise/admin/help/prepare-database-upload.html>`__
52+
in the LGTM admin help.
53+
54+
Query suites
55+
------------
56+
57+
CodeQL includes a new, more flexible, format for query suites. Legacy query
58+
suite definitions are not compatible with the new CodeQL tools. For more
59+
information about CodeQL query suites, see `Creating CodeQL query suites
60+
<https://help.semmle.com/codeql/codeql-cli/procedures/query-suites.html>`__.
61+
62+
Overview of common commands
63+
---------------------------
64+
65+
If you're switching from the legacy ODASA CLI to the new CodeQL CLI,
66+
the table below shows which commands replace the most
67+
common ODASA processes.
68+
69+
+------------------------------------------+---------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
70+
| ``odasa`` command | Corresponding ``codeql`` command | Notes |
71+
+==========================================+===================================================================================================+=========================================================================================================================================================================================================================================================================================================================================================================================================================================================================+
72+
| ``bootstrap`` | n/a | CodeQL analysis does not use ``project`` files during database creation. For more information about creating databases, see `Creating CodeQL databases <https://help.semmle.com/codeql/codeql-cli/procedures/create-codeql-database.html>`__. |
73+
+------------------------------------------+---------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
74+
| ``addSnapshot``, ``addLatestSnapshot`` | n/a | To obtain the version of the code you want to analyze, just run your normal check-out commands. |
75+
+------------------------------------------+---------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
76+
| ``buildSnapshot`` | `database create <https://help.semmle.com/codeql/codeql-cli/commands/database-create.html>`__ | When creating a CodeQL database, you specfiy build commands in the command line, rather than in a project file. For more information, see `Creating CodeQL databases <https://help.semmle.com/codeql/codeql-cli/procedures/create-codeql-database.html>`__. |
77+
+------------------------------------------+---------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
78+
| ``analyzeSnapshot`` | `database analyze <https://help.semmle.com/codeql/codeql-cli/commands/database-analyze.html>`__ | For more information, see `Analyzing databases with the CodeQL CLI <https://help.semmle.com/codeql/codeql-cli/procedures/analyze-codeql-database.html>`__. |
79+
+------------------------------------------+---------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
80+
| ``archiveSnapshot`` | `database cleanup <https://help.semmle.com/codeql/codeql-cli/commands/database-cleanup.html>`__ | Use ``database cleanup`` to reduce the size of a CodeQL database by deleting temporary data. |
81+
+------------------------------------------+---------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
82+
| ``export`` | `database bundle <https://help.semmle.com/codeql/codeql-cli/commands/database-bundle.html>`__ | You don't need to export databases before adding them to VS Code. However, you should "bundle" CodeQL databases before using them with LGTM Enterprise, CodeQL for Eclipse, or CodeQL for Visual Studio. For more information, see `Preparing CodeQL databases to upload to LGTM <https://help.semmle.com/lgtm-enterprise/admin/help/prepare-database-upload.html>`__ in the LGTM admin help and the `Database compatibility notes <#database-compatibility-notes>`__. |
83+
+------------------------------------------+---------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
84+
| ``prepareQueries`` | `query compile <https://help.semmle.com/codeql/codeql-cli/commands/query-compile.html>`__ | Queries are compiled when you run ``database analyze`` and other query-running commands. You can speed up compilation by running ``query compile`` separately using more threads. |
85+
+------------------------------------------+---------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
86+
| ``qltest`` | `test run <https://help.semmle.com/codeql/codeql-cli/commands/test-run.html>`__ | For more information about running regression tests, see `Testing custom queries <https://help.semmle.com/codeql/codeql-cli/procedures/test-queries.html>`__. |
87+
+------------------------------------------+---------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
88+
| ``runQuery`` | `query run <https://help.semmle.com/codeql/codeql-cli/commands/query-run.html>`__ | Use ``query run`` to quickly view results in your terminal. To generate interpreted results that can be viewed in source code, use ``database analyze``. |
89+
+------------------------------------------+---------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
90+
| ``upgrade`` | `database upgrade <https://help.semmle.com/codeql/codeql-cli/commands/database-upgrade.html>`__ | For more information, see `Upgrading CodeQL databases <https://help.semmle.com/codeql/codeql-cli/procedures/upgrade-codeql-database.html>`__. |
91+
+------------------------------------------+---------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

0 commit comments

Comments
 (0)