Skip to main content

database trace-command

[プラミング] トレースされたビルドの一部として単一のコマンドを実行します。

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

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 database trace-command [--threads=<num>] [--ram=<MB>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database> <command>...

説明

[プラミング] トレースされたビルドの一部として単一のコマンドを実行します。

これは、トレーサーの下で単一の特定のコマンド ラインを実行するため、抽出が実行される可能性はありますが、結果の CodeQL データベースは終了されません。

[オプション]

主なオプション

<database>

[必須] 構築中の CodeQL データベースへのパス。 これは、codeql database init を使って抽出するために準備されている必要があります。

--db-cluster オプションを指定した場合、これはデータベース自体ではなく、データベースを "含む" ディレクトリであり、これらのデータベースはすべてまとめて処理されます。__

<command>...

実行するコマンド。 これは、プロセスの作成に使用される 1 つ以上の引数で構成される場合があります。 コマンドの引数と自分の引数を混同しないように、コマンドの引数をリストする前に '--' 引数を渡すことをお勧めします。

コマンドは、状態コード 0 で終了する必要があります。 他の終了コードはエラーと見なされます。

--index-traceless-dbs が指定されている場合、コマンドを省略できます。

-j, --threads=<num>

この数のスレッドを使用することをエクストラクターに要請します。 このオプションは、候補としてエクストラクターに渡されます。 CODEQL_THREADS 環境変数を設定している場合、環境変数の値がこのオプションよりも優先されます。

0 を渡して、マシン上のコアごとに 1 つのスレッドを使ったり、N を渡して、N 個のコアを未使用のままにしたりすることができます (ただし、その場合でも、少なくとも 1 つのスレッドが使われます)。

-M, --ram=<MB>

この量のメモリを使用することをエクストラクターに要請します。 このオプションは、候補としてエクストラクターに渡されます。 CODEQL_RAM 環境変数を設定している場合、環境変数の値がこのオプションよりも優先されます。

--[no-]db-cluster

コマンド ラインで指定されたディレクトリがデータベース自体ではなく、構築中の 1 つ以上のデータベースを "含む" ディレクトリであることを示します。__ これらのデータベースはまとめて処理されます。

--no-tracing

[詳細設定] 指定したコマンドをトレースしません。代わりに、必要なすべてのデータを直接生成するために使用します。

--extra-tracing-config=<tracing-config.lua>

[詳細設定] トレーサー構成ファイルのパス。 ビルド トレーサーの動作を変更するために使用できます。 ビルド コマンドの一部として実行されるコンパイラ プロセスを選び、他のツールの実行をトリガーするために使用できます。 エクストラクターにより、ほとんどの状況で機能する既定のトレーサー構成ファイルが提供されます。

--[no-]index-traceless-dbs

指定したコマンドに加えて、ビルド プロセスのトレースに依存しないエクストラクターに対してメイン スクリプトを実行します。 --db-cluster を使用して複数の言語用のデータベースを構築している場合、このオプションは codeql database trace-command の 1 回の呼び出しに対してのみ指定する必要があります。

--[no-]use-build-mode

データベースのビルド モードに基づいて実行する内容を決定します。 このオプションは、--index-traceless-dbs と同時に使用することはできません。

--working-dir=<dir>

[詳細設定] 指定したコマンドを実行するディレクトリ。 この引数を指定しない場合、--source-rootcodeql database create に渡される の値 (存在する場合) でコマンドが実行されます。 --source-root 引数を指定しない場合、コマンドは現在の作業ディレクトリで実行されます。

--no-run-unnecessary-builds

[詳細設定] ビルド プロセスのトレースに依存するエクストラクターが作成中のデータベースで使用されている場合にのみ、指定したビルド コマンドを実行します。 このオプションを指定しない場合、CodeQL で不要であっても、他の理由で副作用が必要とされているという仮定に基づき、コマンドが実行されます。

エクストラクターの動作を制御するためのオプション

-O, --extractor-option=<extractor-option-name=value>

CodeQL エクストラクターのオプションを設定します。 extractor-option-name は、extractor_name.group1.group2.option_name または group1.group2.option_name という形式にする必要があります。 extractor_option_name がエクストラクター名で始まる場合、指定したエクストラクターはオプション group1.group2.option_name を宣言する必要があります。 それ以外の場合、オプション group1.group2.option_name を宣言するエクストラクターにはオプションが設定されます。 value は、改行を含まない任意の文字列にすることができます。

このコマンド ライン オプションを繰り返し使用して、複数のエクストラクター オプションを設定できます。 同じエクストラクター オプションに複数の値を指定した場合、動作は、エクストラクター オプションで想定されている型によって異なります。 文字列オプションでは、指定した最後の値が使用されます。 配列オプションでは、指定したすべての値が順番に使用されます。 このコマンド ライン オプションを使用して指定したエクストラクター オプションは、--extractor-options-file で指定したエクストラクター オプションの後に処理されます。

codeql database init または codeql database begin-tracing に渡した場合、オプションは間接トレース環境にのみ適用されます。 ワークフローで codeql database trace-command の呼び出しも行う場合は、必要に応じてオプションも渡す必要があります。

各エクストラクターによって宣言されたオプションの一覧を表示する方法など、CodeQL エクストラクター オプションについて詳しくは、https://codeql.github.com/docs/codeql-cli/extractor-options を参照してください。

--extractor-options-file=<extractor-options-bundle-file>

エクストラクター オプションのバンドル ファイルを指定します。 エクストラクター オプション バンドル ファイルは、エクストラクター オプションを設定する JSON ファイル (拡張子 .json) または YAML ファイル (拡張子 .yaml または .yml) です。 ファイルには最上位レベルのマップ キー 'extractor' があり、その下にエクストラクター名が第 2 レベルのマップ キーとして含まれている必要があります。 それ以降のレベルのマップは入れ子になったエクストラクター グループを表し、文字列と配列のオプションは、文字列と配列の値を持つマップ エントリです。

エクストラクター オプション バンドル ファイルは、指定した順序で読み取られます。 異なるエクストラクター オプション バンドル ファイルで同じエクストラクター オプションを指定した場合、その動作はエクストラクター オプションで想定されている型によって異なります。 文字列オプションでは、指定した最後の値が使用されます。 配列オプションでは、指定したすべての値が順番に使用されます。 このコマンド ライン オプションを使用して指定したエクストラクター オプションは、--extractor-option で指定したエクストラクター オプションよりも前に処理されます。

codeql database init または codeql database begin-tracing に渡した場合、オプションは間接トレース環境にのみ適用されます。 ワークフローで codeql database trace-command の呼び出しも行う場合は、必要に応じてオプションも渡す必要があります。

各エクストラクターによって宣言されたオプションの一覧を表示する方法など、CodeQL エクストラクター オプションについて詳しくは、https://codeql.github.com/docs/codeql-cli/extractor-options を参照してください。

共通オプション

-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 以降で使用できます。