クエリのコンパイル

このコンテンツでは、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>...

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 環境変数をオーバーライドします。

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

この記事の内容