ビルドのロードで推奨される手法

背景

Klocwork では、ビルドをロードするときに自動マッチングアルゴリズムを使用して、以前のビルドと比較してどのファイルが変更または移動されたか判断します。これは、ビルド間で指摘をマッチングするための基盤となる機能であり、ビルドの比較結果の精度に大きな影響を及ぼします。

パス置換を使用する

ファイルが正しくマッチングされない場合、指摘データが不整合な状態になり、引用データが失われたり、孤立したりする可能性があります。すべての統合ホストと CI ビルドホストでパス置換を使用して、ソースルートがすべてのビルドで一貫していることを確認してください。

システム、ビルド、および/またはマシン間で変更される可能性があるパスには、パス置換機能を使用してください。これらのいずれかにより、ソース、ライブラリ、外部ツールへのパスが変更されることがあり、その結果、自動マッチングアルゴリズムの実行が妨げられる可能性があります。

たとえば、環境に基づいてパスが異なるソースフォルダー、外部ライブラリ、またはシステムファイルがある場合は、kwbuildproject で --replace-path オプションを使用して、それらのパスが自動調整されるようにする必要があります。そうすれば、さまざまなセットアップでプロジェクトをシームレスに構築および解析するのに役立ちます。

Klocwork 2023.3 の時点で、パス置換機能はすべてのシナリオで動作するように最適化されています。

パス置換の例

Windows パスと Linux パスが完全に一致することはあり得ないため、パス置換はプロジェクトに複数のプラットフォームがある場合に特に役立ちます。また可能な限り、ネットワークパスを置き換える場合にも使用してください。

たとえば、ベースパスが一致しない次のようなシステムがあるとします。

システム 1 (Linux ストリーム 1)

/path/to/our/source/code
/home/james/.maven
/ubuntu/libs
//192.168.0.1/network/path

システム 2 (Linux ストリーム 2)

/custom/made/source/code
/users/jeffry/.maven
/arch/libs
//127.0.0.1/network/path

システム 3 (Windows ストリーム)

C:\workspace\source\code
C:\users\jeffry\.maven
C:\system32\libs
\\10.151.0.23\network\path

パス内に同一のファイルがある場合でも、ファイルを正確に揃えるにはベストエフォートで一致させる必要があります。この種のシステムの不一致の最も一般的な理由は、複数のプラットフォームが同じプロジェクトにロードされるストリームを使用していることです。

解析でパス置換オプションを使用することにより、システムの不一致を解決することができ、それによって、結果の一貫性が向上し、両方のマシンに対して同様の方法で解析が実行されるようになります。

kwbuildproject -f -H <license_server_url> -o tables kwinject.out \

                                     --replace-path /path/to/our/source/code=/source \
                                     --replace-path /home/james/.maven=/maven \
                                     --replace-path /ubuntu/libs=/system \
                                     --replace-path //192.168.0.1/network/path=/buildserver

ファイルの完全一致を有効にする

重要なファイルの場合は、プロジェクトで enable_exact_file_match を使用することを検討してください。そうすることで自動マッチングが無効になり、プロジェクトをより詳細に制御できるようになります。

プロジェクトにロード (および編集) できる .emp ファイルのサポートを追加しました。.emp ファイルはロードされると、その中で指定されたフォルダーのリスト内のファイルに完全一致を適用します。

ワークフローは次のとおりです。

1. kwadmin または validate admin を使用して、enable_exact_file match を有効にします。

   kwadmin set-project-property <project_name> enable_exact_file_match TRUE

2. ポータル上のプロジェクト構成ページから、または次のコマンドを使用して、.emp ファイルをインポートします。

   kwadmin import-config <project_name> file.emp

   ポータル上のプロジェクト構成ページから、既存の .emp ファイルを変更することもできます。

.emp ファイルが空であるか、または存在せず、enable_exact_file_match が true に設定されている場合は、完全一致がすべてのファイルに適用されます。

ファイルマッチングオーバーライドファイルを使用する

Klocwork 2023.3 以降、ファイルマッチングオーバーライドファイルを使用して、ファイルを正しくマッチングできるようになりました。

ファイルマッチングオーバーライドを使用すると、ファイルのマッチング方法と処理方法を手動で指定できるようになります。これは、Git や Helix Core などのバージョン管理システムを扱う場合に特に便利です。

また、オーバーライドを使用することで、次のような、現在自動マッチングを使用できないシナリオも処理できるようになります。

• (ファイルを移動するのではなく) ファイル名を変更する

• 古いファイルを削除済みとしてマークし、どのファイルとも一致しないようにする

• ファイルを新規としてマークし、無関係な削除済みファイルと一致しないようにする

ファイルオーバーライドファイルは、次の 3 つの演算子を含む単純なテキストファイルです。A は追加済み、D は削除済み、R は名前変更済みです。不一致を防ぐために、各ビルド間にオーバーライドファイルを適用することをお勧めします。

R "C:\Perforce\CommandLineTools 24.1\samples\demosthenes\revisions\rev4\roach_bag\mud.c" "C:\Perforce\CommandLineTools 24.1\samples\demosthenes\revisions\rev4\roach_bag\hello.c"

ファイルマッチングオーバーライドの例

例 1

• build_1 に「/root/src/data/test.cpp」という名前のファイルが存在します。

• これは、後で build_2 で削除されます。

• build_3 に「/external/libraries/json/test.cpp」という名前の新しいファイルが追加されます。

自動マッチングが有効であり、オーバーライドファイルが指定されていない場合、誤って「/root/src/data/test.cpp」が「/external/libraries/json/test.cpp」と一致するものとみなされます。

解決策 1

ビルド 2 で削除されたファイルをマークし、ビルド 2 の新しいファイルと一致しないようにすることができます。新しい test.cpp をビルド 3 で新規 (追加) としてマークし、以前のファイルと一致しないようにすることができます。

1. build_2 をロードする前に、次の内容を含むオーバーライドファイル (overrides.txt) を準備します。

   D /root/src/data/test.cpp

2. build_2 をロードするときに、--file-overrides オプションを含めます。

   kwadmin load project tables --file-overrides overrides.txt

3. build_3 をロードする前に、次の内容で新しいオーバーライド ファイルを準備するか、既存のファイルを編集します。

   A /external/libraries/json/test.cpp

4. build_3 をロードするときに、--file-overrides オプションを含めます。

   kwadmin load project tables --file-overrides overrides.txt

解決策 2

2 つの test.cpp ファイル間でルートパスが異なるため、最初のルートパス (/root/src) でのみファイルを検索するように enable_exact_file_match に指示できます。

1. exact_file_match を有効にします。

   kwadmin set-project-property <project_name> enable_exact_file_match TRUE

2. 最初のパス (path_1.emp) で完全一致を検索するために .emp ファイルを準備します。

   /root/src

3. ビルド [構成] > [構成ファイル] > + の下で、ポータル上で完全に一致する構成ファイルを追加します。または、次のコマンドを使用します。

   kwadmin import-config <project_name> path_1.emp

これにより、/root/src ではなく、他のパス (/external/libraries) を対象に行われる自動マッチングが可能になります。

例 2

• build_1 に「/root/src/data/test.cpp」という名前のファイルが存在します。

• 続いて、これは build_2 で「/root/src/data/testUtil.cpp」という名前に変更されます。

これら 2 つのファイルは名前が異なるため、自動マッチングアルゴリズムではマッチングされません。

解決策

1. オーバーライドファイル (overrides.txt) に名前の変更を追加します。

   R /root/src/data/test.cpp /root/src/data/testUtil.cpp

2. オーバーライドファイルを build_2 にロードします。

   kwadmin load project tables --file-overrides overrides.txt

   これにより、「test.cpp」から「testUtil.cpp」に名前変更済みとしてマークされたファイルを含む build_3 が生成されます。

ビルドタグを使用する

Klocwork 2023.3 以降、タグの形式でメタデータをビルドに追加できるようになりました。これらは、プラットフォーム、ブランチ、コミット ID などをビルドに関連付けるために使用できます。これらは、ビルド間のファイルマッチングオーバーライドの生成時に正確な判断を行うために使用できます。

ビルドタグの詳細については、ビルドタグの使用を参照してください。

ストリームを論理的に構造化する

それが最も有効な方法である場合を除き、完全にフラットなストリーム構造は使用しないでください。ストリームを論理的に構造化すると、次のことが可能になります。

• 関連するファイルとディレクトリをグループ化することで、プロジェクトの明確さと保守性が強化される

• ストリームの作成、編集、削除に関して、プロジェクトとストリームの管理を簡素化する

• ファイルマッチングアルゴリズムで、ファイルマッチング時により適切な判断を下せるようになる

ストリーム構造化の例

不良なストリーム構造と良好なストリーム構造の例を以下に示します。比較してみてください。

不良な例 - フラット構造

- demosthenes
  - linux_x64_main
  - linux_x86_main
  - linux_x86_feature_1
  ...
  - windows_x64_main
  ...

良好な例 - 階層構造

- demosthenes
  - linux
    - x64
      - main
        - feature_1
        - feature_2
      - v23.2
        - hotfix_1
    - x86
    ...
  - windows
    ...