hohn/codeql
1
0
Fork 0
mirror of https://github.com/github/codeql.git synced 2026-01-30 06:42:57 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #7571 from github/aeisenberg/remove-upgrades

Browse Source 
Update docs on the output of `resolve qlpacks`
This commit is contained in:
Andrew Eisenberg
2022-01-24 09:02:02 -08:00
committed by GitHub
parent 75f389749a c6deccf863
commit 497c87851c
1 changed files with 51 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
docs/codeql/codeql-cli/getting-started-with-the-codeql-cli.rst
View File

@@ -4,7 +4,7 @@ Getting started with the CodeQL CLI
===================================
To run CodeQL commands, you need to set up the CLI so that it can access
the tools, queries, and libraries required to create and analyze databases.
the tools, queries, and libraries required to create and analyze databases.
.. include:: ../reusables/license-note.rst
@@ -18,16 +18,16 @@ structures. To get started quickly, we recommend adopting a relatively simple
setup, as outlined in the steps below.
If you use Linux, Windows, or macOS version 10.14 ("Mojave") or earlier, simply
follow the steps below. For macOS version 10.15 ("Catalina") or newer, steps 1
and 4 are slightly different---for further details, see the sections labeled
follow the steps below. For macOS version 10.15 ("Catalina") or newer, steps 1
and 4 are slightly different---for further details, see the sections labeled
**Information for macOS "Catalina" (or newer) users**. If you are using macOS
on Apple Silicon (e.g. Apple M1), ensure that the `Xcode command-line developer
tools <https://developer.apple.com/downloads/index.action>`__ and `Rosetta 2
<https://support.apple.com/en-us/HT211861>`__ are installed.
For information about installing the CodeQL CLI in a CI system to create results
to display in GitHub as code scanning alerts, see
`Installing CodeQL CLI in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system>`__
to display in GitHub as code scanning alerts, see
`Installing CodeQL CLI in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system>`__
in the GitHub documentation.
1. Download the CodeQL CLI zip package
@@ -42,9 +42,9 @@ Conditions <https://securitylab.github.com/tools/codeql/license>`__.
There are several different versions of the CLI available to download, depending
on your use case:
- If you want to use the most up to date CodeQL tools and features, download the
version tagged ``latest``.
version tagged ``latest``.
- If you want to create CodeQL databases to upload to LGTM Enterprise, download
the version that is compatible with the relevant LGTM Enterprise version
@@ -53,9 +53,9 @@ Conditions <https://securitylab.github.com/tools/codeql/license>`__.
<https://github.com/github/codeql-cli-binaries/releases>`__ on GitHub. Using the
correct version of the CLI ensures that your CodeQL databases are
compatible with your version of LGTM Enterprise. For more information,
see `Preparing CodeQL databases to upload to LGTM
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.
in the LGTM admin help.
If you use Linux, Windows, or macOS version 10.14 ("Mojave") or earlier, simply
`download the zip archive
@@ -72,12 +72,12 @@ Alternatively, you can download ``codeql.zip``, which contains the CLI for all s
**Information for macOS "Catalina" (or newer) users**
.. pull-quote:: macOS "Catalina" (or newer)
If you use macOS version 10.15 ("Catalina"), version 11 ("Big Sur"), or the upcoming
version 12 ("Monterey"), you need to ensure that your web browser does not automatically
extract zip files. If you use Safari, complete the following steps before downloading
If you use macOS version 10.15 ("Catalina"), version 11 ("Big Sur"), or the upcoming
version 12 ("Monterey"), you need to ensure that your web browser does not automatically
extract zip files. If you use Safari, complete the following steps before downloading
the CodeQL CLI zip archive:
i. Open Safari.
ii. From the Safari menu, select **Preferences...**.
iii. Click the **General** Tab.
@@ -101,22 +101,22 @@ further options on the command line.
3. Obtain a local copy of the CodeQL queries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `CodeQL repository <https://github.com/github/codeql>`__ contains
The `CodeQL repository <https://github.com/github/codeql>`__ contains
the queries and libraries required for CodeQL analysis of C/C++, C#, Java,
JavaScript/TypeScript, Python, and Ruby.
Clone a copy of this repository into ``codeql-home``.
By default, the root of the cloned repository will be called ``codeql``.
Rename this folder ``codeql-repo`` to avoid conflicting with the CodeQL
CLI that you will extract in step 4. If you use git on the command line, you can
clone and rename the repository in a single step by running
Clone a copy of this repository into ``codeql-home``.
By default, the root of the cloned repository will be called ``codeql``.
Rename this folder ``codeql-repo`` to avoid conflicting with the CodeQL
CLI that you will extract in step 4. If you use git on the command line, you can
clone and rename the repository in a single step by running
``git clone git@github.com:github/codeql.git codeql-repo`` in the ``codeql-home`` folder.
The CodeQL libraries and queries for Go analysis live in the `CodeQL for Go
repository <https://github.com/github/codeql-go/>`__. Clone a copy of this
repository into ``codeql-home``.
repository into ``codeql-home``.
The cloned repositories should have a sibling relationship.
The cloned repositories should have a sibling relationship.
For example, if the root of the cloned CodeQL repository is
``$HOME/codeql-home/codeql-repo``, then the root of the cloned CodeQL for Go
repository should be ``$HOME/codeql-home/codeql-go``.
@@ -134,29 +134,29 @@ see ":doc:`About QL packs <about-ql-packs>`."
- For the queries used on `LGTM.com <https://lgtm.com>`__, check out the
``lgtm.com`` branch. You should use this branch for databases you've built
using the CodeQL CLI, fetched from code scanning on GitHub, or recently downloaded from LGTM.com.
The queries on the ``lgtm.com`` branch are more likely to be compatible
with the ``latest`` CLI, so you'll be less likely to have to upgrade
newly-created databases than if you use the ``main`` branch. Older databases
The queries on the ``lgtm.com`` branch are more likely to be compatible
with the ``latest`` CLI, so you'll be less likely to have to upgrade
newly-created databases than if you use the ``main`` branch. Older databases
may need to be upgraded before you can analyze them.
- For the most up to date CodeQL queries, check out the ``main`` branch.
- For the most up to date CodeQL queries, check out the ``main`` branch.
This branch represents the very latest version of CodeQL's analysis. Even
databases created using the most recent version of the CLI may have to be
upgraded before you can analyze them. For more information, see
":doc:`Upgrading CodeQL databases <upgrading-codeql-databases>`."
- For the queries used in a particular LGTM Enterprise release, check out the
branch tagged with the relevant release number. For example, the branch
tagged ``v1.27.0`` corresponds to LGTM Enterprise 1.27. You must use this
version if you want to upload data to LGTM Enterprise. For further
information, see `Preparing CodeQL databases to upload to LGTM
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.
4. Extract the zip archive
~~~~~~~~~~~~~~~~~~~~~~~~~~
For Linux, Windows, and macOS users (version 10.14 "Mojave", and earlier)
For Linux, Windows, and macOS users (version 10.14 "Mojave", and earlier)
simply
extract the zip archive into the directory you created in step 2.
@@ -171,16 +171,16 @@ For example, if the path to your copy of the CodeQL repository is
**Information for macOS "Catalina" (or newer) users**
.. pull-quote:: macOS "Catalina"
macOS "Catalina", "Big Sur", or "Monterey" users should run the following
commands in the Terminal, where ``${install_loc}`` is the path to the
macOS "Catalina", "Big Sur", or "Monterey" users should run the following
commands in the Terminal, where ``${install_loc}`` is the path to the
directory you created in step 2:
i. ``mv ~/Downloads/codeql*.zip ${install_loc}``
ii. ``cd ${install_loc}``
iii. ``/usr/bin/xattr -c codeql*.zip``
iv. ``unzip codeql*.zip``
5. Launch ``codeql``
~~~~~~~~~~~~~~~~~~~~
@@ -191,7 +191,7 @@ executable in a couple of ways:
``<extraction-root>`` is the folder where you extracted the CodeQL CLI
package.
- By adding ``<extraction-root>/codeql`` to your ``PATH``, so that you
can run the executable as just ``codeql``.
can run the executable as just ``codeql``.
At this point, you can execute CodeQL commands. For a full list of the CodeQL
CLI commands, see the "`CodeQL CLI manual <../manual>`__."
@@ -212,16 +212,20 @@ up to create and analyze databases:
- Run ``codeql resolve languages`` to show which languages are
available for database creation. This will list the languages supported by
default in your CodeQL CLI package.
default in your CodeQL CLI package.
- Run ``codeql resolve qlpacks`` to show which QL packs the CLI can find. This
will display the names of the QL packs included in the CodeQL repositories:
``codeql-cpp``, ``codeql-csharp``, ``codeql-go``,
``codeql-java``, ``codeql-javascript``, and ``codeql-python``. The CodeQL
repositories also contain 'upgrade' packs and 'legacy' packs. Upgrade packs
are used by the CLI when you want to upgrade a database so that it can be
analyzed with a newer version of the CodeQL toolchain than was used to create
it. Legacy packs ensure that custom queries and libraries created using older
products are compatible with your version of CodeQL.
will display the names of all the QL packs directly available to the CodeQL CLI.
This should include:
- Query packs for each supported language, for example, ``codeql/{language}-queries``.
These packs contain the standard queries that will be run for each analysis.
- Library packs for each supported language, for example, ``codeql/{language}-all``. These
packs contain query libraries, such as control flow and data flow libraries, that
may be useful to query writers.
- Example packs for each supported language, for example, ``codeql/{language}-examples``.
These packs contain useful snippets of CodeQL that query writers may find useful.
- Legacy packs that ensure custom queries and libraries created using older products are
compatible with your version of CodeQL.
.. _using-two-versions-of-the-codeql-cli:
@@ -242,4 +246,4 @@ recommended directory setup depends on which versions you want to install:
directory. For example, if you unpack version 2.0.2 into
``$HOME/codeql-home/codeql-cli``, the older version should be
unpacked into ``$HOME/codeql-older-version/old-codeql-cli``. Here, the common
grandparent is the ``$HOME`` directory.
grandparent is the ``$HOME`` directory.