qacli validate cibuild

解析を実行し、結果をサーバCIビルドの一部としてValidateにアップロードします。


使用方法

validate cibuild  -P <directory> -b <build-name> [-j <n>] [-I] [--retry <n>] [-o <output-path>] [-T] [-s] [--force-complete] [-c] [--incremental] [--tags <tag[,tag...]>] [-m] [-i][-E <encoding type>] [--] [-h]

詳しい説明

このコマンドはCI環境で結合プロジェクトの解析を実行することを可能にします。

プロジェクトの直近の成功した統合ビルドになかったすべての診断をValidateにアップロードします。これらのすべての診断は解析された処理の一部として報告されるはずです。

これは、DevOps がCIビルドプロセスの一部としてクオリティゲートの実装をすることを可能にします。クオリティゲートはメインの開発ブランチにコミットする前に、新しい診断が識別され、優先度がつけられ、修正または、参照されることを可能にします。

CIビルドの使用に対する前提条件：

  • 有効なCIビルドのライセンス
  • 結合プロジェクトのプロジェクトであること
  • ベースラインとして少なくとも1つの完全な統合ビルドが使用可能であること (qacli validate build　を参照してください)

オプション

オプション名、短縮形 デフォルト 説明
‑‑build‑name, ‑b <build‑name>   （必須）Validateへアップロードするときに使用する固有のビルド名を指定します。ビルド名は実行するビルドジョブと関連のある名前をつけることが推奨されます。
‑‑clean, ‑c   解析を実行する前に、すべての解析データを指定の qaf‑project から削除します。
‑‑disable‑metrics, ‑m   メトリックスのアップロードを無効にします。
‑‑encoding, ‑E   プロジェクトのソースファイルで使用されるエンコードです。デフォルトはユーザのシステムのエンコードです。
‑‑force‑complete   処理段階でのエラーを含み、全ファイルの解析の処理を強制すると、処理の途中で終了してしまいます（ライセンスチェック障害など）。‑s　と同時に実行できません。
‑‑help, ‑h   使用方法の情報を表示し、終了します。
‑‑ignore‑rest, ‑‑   このフラグ以降のラベルの付いた引数をすべて無視します。
‑‑ignore, ‑i   Validate　へアップロードするときの従属性チェックを含むプロジェクトおよび、ファイルチェックを無視します。これによるアップロードは100％完了、正確でない可能性があります。
‑‑incremental   プログラム全体の解析を無効にし、変更のあったファイルのみ解析します。clean　および、inter-tu-dataflow　と相互排他的です。
‑‑inter‑tu‑dataflow, ‑I   翻訳単位間データフロー解析を実行します。
‑‑jobs, ‑j <n>   解析時に同時に実行する処理の最大数を指定します。このオプションのパラメータはすでに設定されている値（qacli config cpu --set <jobs>）および、システムデフォルト（通常コアの数 - 1）をオーバーライドします。
‑‑output‑progress, ‑o   指定したファイルに解析結果が送信されるよう設定します。
‑‑qaf‑project <directory>,
-P <directory> 		  （必須）Perforce QACプロジェクトへの有効なパスを指定します。
‑‑retry <n> 3 ライセンス障害または、パーサが予期しないリターンコードを返したために解析が失敗した場合、短い待機の後最大 n回まで再試行できます。デフォルトの再試行回数は、3回に設定されています。この機能は試行回数をゼロに設定することで無効化できます。
‑‑show‑timings, ‑T   ([nd ]HH:MM:SS)のフォーマットで解析のタイミング情報を表示します。nd は日数を表すので、1以上であるときのみ表示されます。
‑‑stop‑on‑fail, ‑s   最初の解析エラーが発生した時に解析を停止します。‑‑force‑complete　と同時に実行できません。
‑‑tags   Validate　ポータルにアップロードされるCIビルドへカンマで区切られたタグを追加します。個々のタグは最大128文字まで許容され、トータルのタグオプションの最大許容値は256文字です。タグに空白文字を使用することができますが、空白文字は先頭、末尾には使用できません。
‑‑validate‑project, ‑b　   設定がValidateに保存されているPerforce QAC プロジェクト生成時に使用するValidate プロジェクト/ストリームの名前です。

例


一般的なCIビルドの実行

以下の例は CI ビルドを設定し、実行するために　qacli　で行わなければならない手順について示しています。

前提として、静的解析の実行前にソースコードをフェッチし、正常にコンパイルされているものとします。従って、CI環境はすでにソースプロジェクト用に設定済みであると見なします。

必要であるのは　qacli　による静的解析の設定となります。

  1. まず、Validateサーバの認証が完了していない場合はまず、Validateサーバの認証をしてください。 
    qacli auth –-validate –-username <username> --password <password> --url <validate_url> 
  2. その後、Validate　からプロジェクトをフェッチします。 
    qacli validate config --create -P <project_dir> --url <validate_url> --validate-project <validate_project_name> 
  3. ファイルの追加、削除、ソースとの同期による名前の変更など、Perforce QACプロジェクトが最新の情報に更新されていることを確認してください。
    最新のソースとの同期が失敗していると、新しいファイルまたは、名前の変更されたファイルがビルド中に解析されない原因になる可能性があります。

    例: 

    qacli sync -P <project_dir> -t JSON <json_compilation_dbase_path> 

    このコマンドを使用するとソースのビルドに使用されたJSONコンパイルデータベースの内容に基づきPerforce QACプロジェクトが迅速に更新されます。詳細については、プロジェクトの同期を参照してください。

  4. CIビルドを実行します。以下のコマンドでプロジェクトを解析し、その結果をプロジェクトの直近の成功ビルドのベースラインと比較します。 
    qacli validate cibuild -P --build-name ci-build-001 

    新しい結果はValidateサーバに　ci　ビルド名　"ci-build-001"　としてアップロードされます。

    ビルド名が一意であることを確認してください。ビルド名はビルドジョブの発信元と関連のある名前（例えば、JenkinsのジョブIDなど）をつけることが推奨されます。

    CIビルドが完了した後、ビルドの結果が表示されます。 ビルドに新しい問題点が検出されなかった場合、CIビルドのステータスは"Success"　（成功）と表示されます。リターンコードは0です。

    Validateに新しい問題点がアップロードされた場合、ビルドの結果は"Unstable"（不安定）、リターンコード4が表示され、ValidateのCIビルドの結果へのURLが表示されます。 開発者がビルド環境から直接結果を見つけやすいようにするために、ビルドジョブの出力（例えば、Jenkinsなど）にこれをコピーすることができます。


タグを含みCI ビルドをValidate にアップロードする

Validate　に　CIビルドをアップロードし、ビルドにタグを追加するには以下のコマンドを実行します。 

qacli validate cibuild -P . -b matrix --tags "main,Fix1,abcd23df45g" 

インクリメンタルCIビルドの実行

インクリメンタルCIビルドを実行するには、すべてのソースが解析されたプロジェクトのフルビルドが少なくともひとつ必要です。これが、インクメンタルビルドの比較のベースラインになります。

CIビルドに使用されるビルド環境は統合ビルドに使用された環境と一致している必要があります。 また、使用されるすべてのコンパイラは同一バージョンで、同じ場所にインストールされている必要があります。

インクリメンタルビルドは直近の成功したプロジェクトのフルビルドと関連するプロジェクト内の変更のあったファイル（ヘッダから直接または、間接的に）を解析します。

解析される一連のファイルを最小に抑えるため、インクリメンタルCIビルドを実行する前にメインブランチとユーザの使用するブランチのソースを最新に保つことを推奨します。 

qacli validate cibuild -P --build-name ci-build-002 --incremental 
インクリメンタルビルドは特定のプログラム全体の解析機能を無効にします。従って、ファイルが変更されたかどうかに関わらず、すべてのファイルが解析されている場合の結果は様々です。ユーザのCIプロセスがコンプライアンスルールの厳守を求める場合、incrementalオプションを使用するかまたは、ignoreオプションの方がユーザのプロジェクトに適しているかを考慮してください。
CIP 生成のスクリプトについて

必要のない再解析を避けるため、CIP 生成のスクリプトはスタブのインクルードフォルダを決定論的順序で加えるよう記述する必要があります。

古いCIP生成のスクリプトは現在の出荷されているバージョンに基づきアップデートする必要があります。これにより、パイソンの os.walk 関数の結果が正しく処理されていることが確認されます。