Skip to main content

クエリのコンパイル

QL コードをコンパイルまたはチェックします。

この機能を使用できるユーザーについて

GitHub CodeQL は、インストール時にユーザーごとにライセンスされます。 CodeQL は、ライセンスの制限の下で特定のタスクでのみ使用できます。 詳しくは、「CodeQL CLI について」を参照してください。

GitHub Advanced Security ライセンスがある場合は、CodeQL を使用して、自動分析、継続的インテグレーション、継続的デリバリーを行うことができます。 詳しくは、「GitHub Advanced Security について」を参照してください。

この記事の内容

このコンテンツでは、CodeQL CLI の最新リリースについて説明します。 このリリースについて詳しくは、 https://github.com/github/codeql-cli-binaries/releases をご覧ください。

以前のリリースの、このコマンドで使えるオプションを詳しく確認するには、ターミナルで --help オプションを指定してコマンドを実行してください。

構文

Shell
codeql query compile [--check-only] [--keep-going] [--threads=<num>] [--ram=<MB>] <options>... -- <file>...

説明

QL コードをコンパイルまたはチェックします。

1 つ以上のクエリをコンパイルします。 通常、このコマンドの主な結果は、クエリのコンパイル済みバージョンが_コンパイル キャッシュ_に書き込まれ、後でクエリが実行されたときに見つかることです。 その他の出力オプションは、主にデバッグ用です。

[オプション]

主なオプション

<file>...

[必須] コンパイルするクエリ。 各引数は、次のいずれかです。

  • コンパイルする ql ファイル。
  • .ql ファイルを再帰的に検索するディレクトリ。
  • 特定のクエリ セットを定義する .qls ファイル。
  • インストールされている QL パックの 1 つによってエクスポートされた "既知の" .qls ファイルのベース名。

-n, --check-only

QL が有効であることを確認し、エラーを出力するだけです。実際にはクエリ プランを最適化して格納しません。 これは、完全コンパイルよりもはるかに高速な場合があります。

--[no-]precompile

[詳細設定] コンパイルされた各クエリをバイナリ .qlx ファイルとして .ql ソースの横に保存します。

これは、配布用のクエリ パックを準備するときにのみ使用することを想定しています (この場合、codeql pack publish によって自動的に使用されます)。 .qlx ファイルが存在すると、クエリを実行するその後のコマンドでは、コンパイル済みバージョンが優先されて QL ソースへの変更が無視される場合があります。

使用頻度の低いコンパイル オプションの中には、これと互換性がないものがあり、実行時エラーが発生します。

v2.12.0 以降で使用できます。

--[no-]dump-dil

[詳細設定] コンパイル中に、最適化された DIL 中間表現を標準出力に出力します。

JSON 出力が選択されている場合、DIL は単一行の文字列の配列として表され、どのクエリがコンパイルされるかを識別するためにラップされます。

-k, --[no-]keep-going

エラーが見つかってもコンパイルを続行します。

--[no-]dump-ra

[詳細設定] コンパイル中に、最適化された RA クエリ プランを標準出力に出力します。

JSON 出力が選択されている場合、RA は単一行の文字列の配列として表され、どのクエリがコンパイルされるかを識別するためにラップされます。

--format=<fmt>

出力形式 (text (既定値) または json) を選択します。__

-j, --threads=<num>

この数のスレッドをクエリのコンパイルに使用します。

既定値は 1 です。 0 を渡して、コンピューター上のコアごとに 1 つのスレッドを使用したり、N を渡して、N 個のコアを未使用のままにしたりすることができます (ただし、その場合でも、少なくとも 1 つのスレッドが使用されます)。

-M, --ram=<MB>

コンパイラで使用できる必要がある RAM の合計量を設定します。

QL バリアントとコンパイラ制御オプション

--warnings=<mode>

QL コンパイラからの警告を処理する方法。 つぎのいずれかです。

hide: 警告を表示しません。

show (デフォルト値): 警告を出力しますが、コンパイルを続行します。__

error: 警告をエラーとして扱います。

--no-debug-info

デバッグ目的で RA にソースの場所情報を出力しないでください。

--[no-]fast-compilation

[非推奨] [詳細設定] 特に速度の遅い最適化手順を省略します。

--no-release-compatibility

[詳細設定] 移植性を犠牲にして、最新のコンパイラ機能を使用します。

場合によっては、新しい QL 言語機能とエバリュエーターの最適化が、それらが QL コンパイラにおいてデフォルトで有効になる数リリース前に、QL エバリュエーターによってサポートされます。 これにより、最新の CodeQL リリースでクエリを開発するときに生じるパフォーマンスを、コード スキャンまたは CI 統合にまだ使用されている可能性がある少し古いリリースと一致させることができます。

クエリが他の (以前または以降の) CodeQL リリースと互換性があるかどうかを気にする必要がない場合は、このフラグを使用してコンパイラの最近の改善を早期に有効にすることで、パフォーマンスを多少向上させることができます。

リリースに有効にすべき最近の改善がない場合、このオプションは通知することなく何も実行しません。 このため、グローバル CodeQL 構成ファイルで一度にすべて設定しても安全です。

v2.11.1 以降で使用できます。

--[no-]local-checking

使用される QL ソースの部分に対してのみ最初のチェックを実行します。

--no-metadata-verification

QLDoc コメントに埋め込まれたクエリ メタデータの有効性はチェックされません。

--compilation-cache-size=<MB>

[詳細設定] コンパイル キャッシュ ディレクトリの、デフォルトの最大サイズをオーバーライドします。

--fail-on-ambiguous-relation-name

[詳細設定] コンパイル中にあいまいな関係名が生成された場合、コンパイルを失敗とします。

コンパイル環境を設定するためのオプション

--search-path=<dir>[:<dir>...]

QL パックが見つかる可能性があるディレクトリの一覧。 各ディレクトリは、QL パック (またはルートに .codeqlmanifest.json ファイルを含むパックのバンドル)、または 1 つ以上のこのようなディレクトリの直接の親ディレクトリのいずれかです。

パスに複数のディレクトリを含める場合は、それらの順序で、それらの間の優先順位を定義します。解決する必要があるパック名が複数のディレクトリ ツリーで一致する場合は、最初に指定したものが優先されます。

オープンソースの CodeQL リポジトリのチェックアウトでこれを指定すると、そこにある言語の 1 つを照会するときに機能するはずです。

CodeQL リポジトリを、アンパックされた CodeQL ツールチェーンの兄弟としてチェックアウトしている場合、このオプションを指定する必要はありません。このような兄弟ディレクトリは、他の方法では見つからない QL パックについて常に検索されます (このデフォルトが機能しない場合は、ユーザーごとの構成ファイルで --search-path を一度だけ設定することを強くお勧めします)。

(注: Windows では、パスの区切り記号は ; です)。

--additional-packs=<dir>[:<dir>...]

このディレクトリ リストを指定した場合、ディレクトリは、--search-path で指定したものより前に、パックについて検索されます。 これらの間の順序は重要ではありません。このリストの 2 か所でパック名が見つかった場合は、エラーです。

これは、デフォルトのパスにも表示される新しいバージョンのパックを一時的に開発している場合に役立ちます。 一方、構成ファイルでこのオプションをオーバーライドすることは "お勧めしません"。内部アクションによっては、このオプションがオンザフライで追加され、構成済みの値がオーバーライドされます。__

(注: Windows では、パスの区切り記号は ; です)。

--library-path=<dir>[:<dir>...]

[詳細設定] QL ライブラリの生インポート検索パスに追加するオプションのディレクトリ リスト。 これを使う必要があるのは、QL パックとしてパッケージ化されていない QL ライブラリを使用する場合のみです。

(注: Windows では、パスの区切り記号は ; です)。

--dbscheme=<file>

[詳細設定] どの dbscheme クエリに対してコンパイルする必要があるかを明示的に定義します。 これは、自分が何をしているかを確信している呼び出し元のみが指定する必要があります。

--compilation-cache=<dir>

[詳細設定] コンパイル キャッシュとして使用する追加のディレクトリを指定します。

--no-default-compilation-cache

[詳細設定] クエリを含む QL パックや CodeQL ツールチェーン ディレクトリなどの標準の場所でコンパイル キャッシュを使用しません。

CodeQL パッケージ マネージャーを構成するためのオプション

--registries-auth-stdin

<registry_url>=<token> ペアのコンマ区切りのリストを渡して、GitHub Enterprise Server コンテナー レジストリに対して認証を行います。

たとえば、https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 を渡して、 2 つの GitHub Enterprise Server インスタンスに対して認証を行うことができます。

これを使って、CODEQL_REGISTRIES_AUTH および GITHUB_TOKEN 環境変数をオーバーライドします。 github.com コンテナー レジストリに対する認証のみが必要な場合は、代わりに、より単純な --github-auth-stdin オプションを使って認証できます。

--github-auth-stdin

標準入力を介して github.com GitHub Apps トークンまたは個人用アクセス トークンを渡して、github.com コンテナー レジストリに対して認証を行います。

GitHub Enterprise Server コンテナー レジストリに対して認証を行うには、--registries-auth-stdin を渡すか、CODEQL_REGISTRIES_AUTH 環境変数を使います。

これを使って、GITHUB_TOKEN 環境変数をオーバーライドします。

共通オプション

-h, --help

このヘルプ テキストを表示します。

-J=<opt>

[詳細設定] コマンドを実行している JVM にオプションを指定します

(スペースを含むオプションは正しく処理されないことに注意してください)。

-v, --verbose

出力される進行状況メッセージの数を段階的に増やします。

-q, --quiet

出力される進行状況メッセージの数を段階的に減らします。

--verbosity=<level>

[詳細設定] 詳細レベルを、errors、warnings、progress、progress+、progress++、progress+++ のいずれかに明示的に設定します。 -v-q がオーバーライドされます。

--logdir=<dir>

[詳細設定] タイムスタンプと実行中のサブコマンドの名前を含む生成された名前を使用して、指定されたディレクトリ内の 1 つまたは複数のファイルに詳細なログを書き込みます

(完全に制御できる名前でログ ファイルを書き込むには、代わりに --log-to-stderr を指定し、必要に応じて stderr をリダイレクトします)。

--common-caches=<dir>

[[詳細設定] ダウンロードした QL パックやコンパイル済みクエリ プランなど、CLI の複数の実行間に保持される、ディスク上でキャッシュされたデータの場所を制御します。 明示的に設定されない場合、デフォルトではユーザーのホーム ディレクトリに名前が付けられた .codeql ディレクトリになります。まだ存在しない場合は作成されます。

v2.15.2 以降で使用できます。