Jenkins を使用した Polyspace 解析のサンプル スクリプト
継続的インテグレーション プロセスでは、開発者はコードを共有リポジトリに送信します。Jenkins® などのツールを使用する自動ビルド システムでは、定期的にまたは事前定義トリガーに基づいて送信されたコードのビルドとテストが行われ、コードが統合されます。このプロセスの一環として Polyspace® 解析を実行できます。
このトピックでは、Polyspace Bug Finder™ Server™ を使用して Polyspace 解析を実行し、PolyspaceAccess™ Web インターフェイスでレビューのために結果をアップロードするサンプル Shell スクリプトについて説明します。またこのスクリプトでは、レビュー担当者に電子メール通知が送信されます。通知を受信したレビュー担当者は、Polyspace Access Web インターフェイスにログインし (Polyspace Access ライセンスを所有している場合)、結果をレビューします。
開発プロセスへのサンプル スクリプトの拡張
スクリプトは、特定の開発ツールチェーンを対象として作成されていますが、プロジェクト、チーム、または組織で使用されているプロセスに容易に拡張できます。また、スクリプトは Jenkins フリースタイル プロジェクトで実行されることを意図して作成されています。Jenkins Pipeline を使用する場合は、Polyspace 解析用のサンプル Jenkins Pipeline スクリプトを参照してください。
特に、スクリプトは次のような特性を持つことに注意してください。
Linux® でのみ実行される。
スクリプトは、
exportなどいくつかの Linux 固有のコマンドを使用します。ただし、これらのコマンドは Polyspace ワークフローに必須というわけではありません。Windows® スクリプト (.batファイル) を作成する場合は、代わりに同等の Windows コマンドを使用します。Polyspace プラグインをインストールしている場合にのみ、Jenkins と動作する。
スクリプトは、次の 2 通りの方法で Jenkins プラグインに対応するように作成されています。
スクリプトは、補助関数
$ps_helperおよび$ps_helper_accessを使用することでスクリプトを簡潔にしています。これらの補助関数は Polyspace の結果を電子メールの添付ファイル用にエクスポートし、コマンド ライン ユーティリティを使用して結果をフィルタリングします。これらの補助関数は、Jenkins プラグインでのみ使用可能です。ただし、基となるコマンドは Polyspace Bug Finder Server インストールに含まれています。Jenkins 以外のビルド自動化ツールでこれらの補助関数を作成するには、
polyspace-report-generatorコマンドまたはpolyspace-access -export(Polyspace Access)コマンドを使用します。Polyspace Bug Finder Server の結果を含む電子メール通知の送信を参照してください。Jenkins で分散ビルドを実行する場合は、マスター ノードと、Polyspace 解析を実行するエージェント ノードの両方で、同じオペレーティング システムの同じフォルダーにプラグインがインストールされている必要があります。そうでない場合、補助関数を使用できません。
スクリプトにより、カスタマイズされた電子メール用の、電子メール添付用のテキスト ファイル、件名、本文が作成されます。Jenkins に Polyspace プラグインをインストールすると、電子メール プラグインの拡張機能が Jenkins プロジェクトで使用可能になります。この電子メール プラグインにより、以前に作成した件名、本文、および添付ファイルを使用して、カスタマイズされた電子メールを簡単に送信できます。Polyspace プラグインがインストールされていない場合は、電子メールを送信する代わりの手段を見つける必要があります。
Bug Finder 解析を実行する。
スクリプトは、デモ サンプル
Bug_Finder_Exampleに対して Bug Finder を実行します。Polyspace Bug Finder Server 製品をインストールしている場合、デモ サンプルが含まれているフォルダーはpolyspaceserverroot/polyspace/examples/cxx/Bug_Finder_Examplepolyspaceserverroot/usr/local/Polyspace Server/R2019a/です。Code Prover を実行するようにスクリプトを容易に変更できます。
polyspace-bug-finder-serverをpolyspace-code-prover-serverで置き換えます。Code Prover 専用のデモ サンプルCode_Prover_Exampleを使用できます。
前提条件
サーバーで Polyspace 解析を実行し、Polyspace Access Web インターフェイスで結果を確認するには、次の 1 回限りの設定を実行する必要があります。
解析を実行するには、Polyspace Server 製品のインスタンスを 1 つインストールする必要があります。
結果をアップロードするには、Polyspace Access の Web インターフェイスをホストするために必要なコンポーネントを設定する必要があります。
アップロードされた結果を表示するには、(結果をレビューする開発者の各々が) 1 つの Polyspace ライセンスを所有していなければなりません。
同様の要件は、サーバー上での PolyspaceCode Prover™ 解析に適用されます。
Polyspace Server および Access 製品のインストールを参照してください。
Polyspace プラグインをインストールするには、Jenkins インターフェイスの左側にある [Manage Jenkins] を選択します。[Manage Plugin] を選択します。Polyspace プラグインを検索し、ダウンロードしてインストールします。
Jenkins での Polyspace プロジェクトの設定
Polyspace プラグインのインストール後に Jenkins で Polyspace 解析を設定する手順を、以下で説明します。この手順は Jenkins version 2.150.1 に対応していることに注意してください。ご使用の Jenkins のバージョンと Polyspace プラグイン インストールでは、手順が多少異なることがあります。
他のビルド自動化ツールを使用する場合は、同様の設定手順を実行できます。
Polyspace コマンドのパスと Polyspace Access Web インターフェイスのサーバー詳細の指定
Polyspace コマンドが含まれているフォルダーの絶対パスと、Polyspace Access Web インターフェイスをホストするサーバーのホスト名およびポート番号を指定します。パスを指定した後は、結果をアップロードするために、コマンドの絶対パスやサーバー詳細をスクリプトで使用する必要はなくなります。
Jenkins インターフェイスの左側にある [Manage Jenkins] を選択します。[Configure System] を選択します。
[Polyspace] セクションで以下を指定します。
Polyspace コマンドのパス。
パスは
polyspaceserverroot/polyspace/binpolyspaceserverroot/usr/local/Polyspace Server/R2019a/です。
Polyspace Access Web インターフェイスをホストするサーバーが使用するホスト名、ポート番号、およびプロトコル (
httpまたはhttps)。
[Name] フィールドでは、Jenkins プロジェクトで後で使用する、便利な省略表記を定義できます。
[E-mail Notification] セクションに、会社の SMTP サーバー (および電子メールの送信に必要なその他の詳細情報) を指定します。
Polyspace を実行するための Jenkins プロジェクトの作成
Jenkins プロジェクト (フリースタイル プロジェクトなど) を作成するときに、先ほど定義したグローバル省略表記を使用して Polyspace パスを参照できます。
Polyspace を実行するための Jenkins プロジェクトを作成するには、次のようにします。
Jenkins インターフェイスの左側にある [New Item] を選択します。[Freestyle Project] を選択します。
プロジェクトの [Build Environment] セクションで、先に定義した 2 つの省略表記名を入力します。
Polyspace コマンドが含まれているフォルダーのパス名
PolyspaceAccess Web インターフェイスをホストするサーバーの詳細情報の名前。
PolyspaceAccess Web インターフェイスへのアップロードに使用できるログインとパスワードも入力します。ログインとパスワードは、Polyspace Access ライセンスに関連付けられている必要があります。
プロジェクトの [Build] セクションに、Polyspace コマンドと、Polyspace Access Web インターフェイスをホストするサーバーの詳細情報を使用するスクリプトを入力できます。スクリプトが Polyspace 解析を実行し、結果を Polyspace Access Web インターフェイスにアップロードします。
プロジェクトの [Post-build Actions] セクションで、解析後に送信する電子メールのアドレスと添付ファイルを設定します。
Bug Finder の実行、結果のアップロード、および共通の通知の送信を行うスクリプト
このスクリプトは、Bug Finder 解析を実行し、結果をアップロードし、全受信者に送信する共通の通知メールに添付する、影響度の高い欠陥をエクスポートします。
このスクリプトでは、現行フォルダーに、.c ファイルがある sources フォルダーが含まれていることを前提としています。そうでない場合は、gcc -c sources/*.c 行をソースの絶対パスに変更してください。
set -e
export RESULT=ResultBF
export PROG=Bug_Finder_Example
export PARENT_PROJECT=/public/BugFinderExample_PRS_01
# ================================================================
# Trace build command and create an options file
build_cmd="gcc -c sources/*.c"
polyspace-configure \
-allow-overwrite \
-allow-build-error \
-prog $PROG \
-author jenkins \
-output-options-file $PROG.psopts \
$build_cmd
# ================================================================
# Run Bug Finder on the options file
polyspace-bug-finder-server -options-file $PROG.psopts -results-dir $RESULT
# ================================================================
# Upload results to Polyspace Access web interface
$ps_helper_access -create-project $PARENT_PROJECT
$ps_helper_access \
-upload $RESULT \
-parent-project $PARENT_PROJECT \
-project $PROG
# ================================================================
# Export results filtered for defects with "High" impact
$ps_helper_access \
-export $PARENT_PROJECT/$PROG \
-output Results_All.tsv \
-defects High
# ================================================================
# Finalize Jenkins status
exit 0スクリプトの実行後に、エクスポートされたファイル Results_All.tsv が添付された電子メールを全受信者に送信するビルド後のアクションを作成できます。
このスクリプトでは、$ps_helper_access は、ホスト名、ポート、ログイン、および暗号化パスワードを指定するオプションを含む polyspace-access (Polyspace Access) コマンドの省略表記です。その他の polyspace-access オプションは、スクリプトに明示的に記述されます。
Bug Finder の実行、結果のアップロード、カスタマイズされた通知の送信を実行するスクリプト
このスクリプトは、前述の Bug Finder 解析を実行して、結果をアップロードします。ただし、このスクリプトは次の点で前述のスクリプトとは異なります。
このスクリプトはコマンドの実行時にメッセージを出力する関数
run_commandを使用します。この関数は、コンソール出力でスクリプトのどの部分が実行されているかを確認するときに役立ちます。このスクリプトは、結果のエクスポート時にオーナーごとに個別の結果ファイルを作成します。
メイン ファイル
Results_All.tsvにはすべての結果が含まれています。このファイルは電子メールの添付ファイルとしてマネージャーに送信されます。マネージャー宛ての電子メールは、ビルド後のステップで設定されます。ファイルに含まれる欠陥が 10 を超える場合、ビルド ステータスは失敗と見なされます。スクリプトは電子メール通知でステータス
UNSTABLEを送信します。userA用にエクスポートされた結果ファイルResults_Users_userA.tsvには、Programming グループの欠陥のうち、影響度が高い欠陥が含まれています。この結果ファイルは電子メールの添付ファイルとして
userAに送信されます。userB用にエクスポートされた結果ファイルResults_Users_userB.tsvには、関数bug_memstdlib()からの欠陥が含まれています。この結果ファイルは電子メールの添付ファイルとして
userBに送信されます。
メールの件名を含むファイルは、それぞれ個別に作成されます。マネージャーの件名はファイル
mailsubject_manager.txtに、userAの件名はファイルmailsubject_user_userA.txtに、userBの件名はファイルmailsubject_user_userB.txtにそれぞれ作成されます。ファイル
mailbody_manager.txtには、マネージャー宛ての電子メールの本文が作成されます。
このスクリプトは次のことを前提としています。
現行フォルダーに、
.cファイルがあるフォルダーsourcesが含まれていること。そうでない場合は、
gcc -c sources/*.c行をソースの絶対パスに変更してください。userAおよびuserBという名前のユーザーがいること。特に電子メール アドレスuserA@companyname.comとuserB@companyname.com(先に設定したユーザー名と SMTP サーバーから決定される) は、実際の電子メール アドレスにする必要があります。名前は実際のユーザー名に置き換えてください。
set -e
export RESULT=ResultBF
export PROG=Bug_Finder_Example
export REPORT=Results_List.tsv
# ================================================================
# Define function to print message while running command
run_command()
{
# $1 is a message
# $2 $3 ... is the command to dump and to run
message=$1
shift
cat >> mailbody_manager.txt << EOF
$(date): $message
EOF
"$@"
}
# ================================================================
# Initialize mail body
cat > mailbody_manager.txt << EOF
Dear Manager(s)
Here is the report of the Jenkins Job ${JOB_NAME} #${BUILD_NUMBER}
It contains all Red Defect found in Bug Finder Example project
EOF
# ================================================================
# Trace build command and create options file
build_cmd="gcc -c sources/*.c"
run_command "Tracing build command", \
polyspace-configure \
-allow-overwrite \
-allow-build-error \
-prog $PROG \
-author jenkins \
-output-options-file $PROG.psopts \
$build_cmd
# ================================================================
# Run Bug Finder on the options file
run_command "Running Bug finder" \
polyspace-bug-finder-server -options-file $PROG.psopts -results-dir $RESULT
# ================================================================
# Upload results to Polyspace Access web interface
run_command "Creating Project $PARENT_PROJECT" \
$ps_helper_access -create-project $PARENT_PROJECT
run_command "Uploading on $PARENT_PROJECT/$PROG" \
$ps_helper_access \
-upload $RESULT \
-parent-project $PARENT_PROJECT \
-project $PROG \
-output upload.output
PROJECT_RUNID=$($ps_helper prs_print_runid upload.output)
PROJECT_URL=$($ps_helper prs_print_projecturl upload.output $POLYSPACE_ACCESS_URL)
# ================================================================
# Export report
run_command "Exporting report from $PARENT_PROJECT/$PROG" \
$ps_helper_access \
-export $PROJECT_RUNID \
-output $REPORT \
-defects High
# ================================================================
# Filter Reports
run_command "Filtering reports for defects" \
$ps_helper report_filter \
$REPORT \
Results_All.tsv \
Family Defect \
# ================================================================
# Filter Reports for userA and userB
run_command "Filtering Reports for userA: Group=='Programming' and Information=='Impact: High'" \
$ps_helper report_filter \
$REPORT \
Results_Users.tsv \
userA \
Group Programming \
Information "Impact: High"
run_command "Filtering Reports for userB: Function=='bug_memstdlib()'" \
$ps_helper report_filter \
$REPORT \
Results_Users.tsv \
userB \
Function "bug_memstdlib()"
# ================================================================
# Update Jenkins status
# Jenkins build status is unstable when there are more than 10 Defects
BUILD_STATUS=$($ps_helper report_status Results_All.tsv 10)
# ================================================================
# Update mail body and mail subject
NB_FINDINGS_ALL=$($ps_helper report_count_findings Results_All.tsv)
NB_FINDINGS_USERA=$($ps_helper report_count_findings Results_Users_userA.tsv)
NB_FINDINGS_USERB=$($ps_helper report_count_findings Results_Users_userB.tsv)
cat >> mailbody_manager.txt << EOF
Number of defects: $NB_FINDINGS_ALL
Number of findings owned by userA: $NB_FINDINGS_USERA
Number of findings owned by userB: $NB_FINDINGS_USERB
All results are uploaded in: $PROJECT_URL
Build Status: $BUILD_STATUS
EOF
cat >> mailsubject_manager.txt << EOF
Jenkins for Manager - Polyspace run completed with status $BUILD_STATUS and $NB_FINDINGS_ALL findings
EOF
for user in userA userB
do
echo "Jenkins for $user - $($ps_helper report_count_findings Results_Users_$user.tsv)) findings" > mailsubject_user_$user.txt
done
# ================================================================
# Exit with correct build status
[ "$BUILD_STATUS" != "SUCCESS" ] && exit 129
exit 0
スクリプトの実行後に、エクスポートしたファイル Results_All.tsv を添付した電子メールをマネージャーに送信する、ビルド後のアクションを作成できます。[Recipients] フィールドに電子メール アドレスを指定し、[Mail Subject] フィールドに電子メールの件名を指定し、[Mail Body] フィールドに電子メールの本文を指定します。
また、userA には Results_Users_userA.tsv ファイルを添付した電子メールが、userB には Results_Users_userB.tsv ファイルを添付した電子メールが、それぞれに送信されます (メールの件名はそれぞれ mailsubject_user_userA.txt と mailsubject_user_userB.txt の内容です)。電子メール アドレスは userA@companyname.com と userB@companyname.com です (先に設定したユーザー名と SMTP サーバーから決定される)。
このスクリプトは、補助関数 $ps_helper を使用して、グループ、影響度、および関数に基づいて結果をフィルタリングします。この補助関数はコマンド ライン ユーティリティを使用して、メイン ファイルをフィルタリングして結果を絞り込み、オーナーごとに個別の結果ファイルを作成するなどのアクションを実行します。この関数は次のアクションを引数として取ります。
report_filter:エクスポートしたテキスト ファイルの結果を、テキスト ファイルの内容に基づいてフィルタリングします。次に例を示します。
ファイル$ps_helper report_filter \ Results_List.tsv \ Results_Users.tsv \ userA \ Group Programming \ Information "Impact: High"Results_List.tsvを読み取り、ファイルResults_Users_userA.tsvに書き込みます。テキスト ファイルResults_List.tsvには、GroupおよびInformationの列が含まれています。Group列にProgrammingが含まれており、Information列にImpact: Highが含まれている行のみが、ファイルResults_Users_userA.tsvに書き込まれます。report_status:ファイル内の結果の数に基づいてUNSTABLEまたはSUCCESSを返します。次に例を示します。
ファイルBUILD_STATUS=$($ps_helper report_status Results_All.tsv 10))
Results_All.tsvに含まれる結果 (行) の数が 10 を超えている場合にはUNSTABLEを返します。report_count_findings:ファイル内の結果の数を報告します。次に例を示します。
ファイルNB_FINDINGS_ALL=$($ps_helper report_count_findings Results_All.tsv)
Results_All.tsv内の結果 (行) の数を返します。prs_print_projecturl:ホスト名とポート番号を使用して、Polyspace Access Web インターフェイスの URL を作成します。次に例を示します。
(PROJECT_URL=$($ps_helper prs_print_projecturl Results_All.tsv $POLYSPACE_ACCESS_URL)
polyspace-accessコマンドによりエクスポートされる) ファイルResults_All.tsvを読み取り、Polyspace Access Web インターフェイスの URL を$POLYSPACE_ACCESS_URLに、現在のプロジェクトの URL を$PROJECT_URLに抽出します。
参考
polyspace-bug-finder-server | polyspace-code-prover-server (Polyspace Code Prover) | polyspace-report-generator | polyspace-configure
トピック
- サーバーでの Polyspace Bug Finder の実行と Web インターフェイスへの結果のアップロード
- Manage Polyspace Access Results and Users at the Command Line (Polyspace Access)
- Polyspace Bug Finder Server の結果を含む電子メール通知の送信
- Polyspace 解析用のサンプル Jenkins Pipeline スクリプト
- Offload Polyspace Analysis from Continuous Integration Server to Another Server
