MATLAB プロジェクトと Jenkins を使用した継続的インテグレーション

この例では、継続的インテグレーション用に MATLAB^® プロジェクトを設定し、Jenkins^® で MATLAB ユニットテストのスイートを実行する方法を説明します。

リモートリポジトリにホストされている MATLAB プロジェクトにアクセスするようにフリースタイル Jenkins プロジェクトを構成します。
すべてのプロジェクトテストを実行するビルドステップを Jenkins プロジェクトに追加します。
最新の変更により影響を受けるテストを実行するためのビルドステップを、Jenkins プロジェクトに追加します。
依存関係の分析キャッシュファイルをアーカイブして再利用するビルド後のステップを追加して、変更を検定するときのテストスイートのランタイムを削減します。
プロジェクトをビルドし、テスト結果を確認します。

メモ

Azure^® DevOps、Bamboo^®、GitHub^® Actions などのさまざまな継続的インテグレーション (CI) プラットフォームを使用して、MATLAB コードと Simulink^® モデルを自動ワークフローの一部として実行できます。サポートされている CI プラットフォームの一覧については、CI プラットフォーム上での MATLAB との継続的インテグレーションを参照してください。

前提条件

開始前に、以下を実行します。

Jenkins をインストールします。https://www.jenkins.io/doc/book/installing/を参照してください。
Jenkins 用の MATLAB プラグインをインストールします。
1. Jenkins 内から [Manage Jenkins] ページで [Manage Plugins] をクリックします。
2. [Available] タブで、"MATLAB" を探します。
3. プラグインをダウンロードしてインストールします。
詳細については、Plugin Configuration Guide (GitHub) を参照してください。
MATLAB プロジェクトを Git™ ソース管理下に置き、GitHub で共有します。
1. プロジェクトを読み込んだ状態で、[プロジェクト] タブで [共有]、[GitHub] を選択します。
2. GitHub ユーザー名と個人用アクセストークンを入力し、新しいリポジトリの名前を編集します。[作成] をクリックします。
MATLAB プロジェクトは GitHub で公開されます。GitHub アカウントで設定を変更して、リポジトリを非公開にすることができます。

Jenkins での継続的インテグレーション用 MATLAB プロジェクトの設定

新しい Jenkins プロジェクトを作成します。

Jenkins インターフェイスの左側のペインで、[New Item] をクリックします。
Jenkins プロジェクトの名前を入力し、[Freestyle project] を選択し、[OK] をクリックします。

Jenkins プロジェクトを構成します。左側のペインで [Configure] をクリックします。

[Source Code Management] セクションで、MATLAB プロジェクトをホストする [Repository URL] を指定します。たとえば、「https://github.com/username/Airframe-Example.git」と指定します。
[Build Triggers] セクションで、ビルドを実行するタイミングと頻度を指定できます。たとえば、すべての GitHub プッシュ通知の後にプロジェクトをビルドするには、[GitHub hook trigger for GITScm polling] を選択します。
[Build Environment] セクションで、[Use MATLAB Version] を選択し、[MATLAB root] に「C:\Program Files\MATLAB\R2022a」などと指定します。
実行するテストスイートを指定するには、[Build] セクションで、[Add Build Step]、[Run MATLAB Tests] を選択します。特定のフォルダーに保存されているすべてのテストを実行するには、[By folder name] を選択し、テストフォルダーの名前を指定します。たとえば、「tests」と指定します。既定では、[Run MATLAB Test] を選択すると、MATLAB プロジェクト内のすべてのテストファイルが実行されます。
または、[Run MATLAB Command] ステップを使用して、MATLAB プロジェクトラベルを使用しているすべてのテストを実行します。[Build] セクションで、[Add Build Step]、[Run MATLAB Command] を選択します。[Command] フィールドに、以下のスクリプトを入力します。
```
proj = openProject("ProjectAirframeExample.prj");
testFiles = findFiles(proj,Label="Test");
runtests(testFiles)
```
Jenkins プロジェクトの構成を保存するには、[Save] をクリックします。
プロジェクトをビルドし、すべてのテストを実行するには、[Build Now] をクリックします。Jenkins は、ビルドをトリガーし、[Build History] でビルドに番号を割り当て、ビルドを実行します。ビルドに成功すると、ビルド番号の横に青い円形アイコンが表示されます。ビルドに失敗すると、赤い円形アイコンが表示されます。詳細については、Run MATLAB Tests on Jenkins Server (GitHub) を参照してください。

依存関係のキャッシュと影響分析を使用した、テストのランタイムの削減

依存関係キャッシュファイルを共有することで、ローカルマシンと CI サーバーでの検定時間を削減できます。事前設定された依存関係キャッシュファイルを使用すれば、インクリメンタルな影響分析を実行し、変更の影響を受けるテストのみを実行することができます。

MATLAB プロジェクトの依存関係キャッシュファイルの設定

プロジェクトの依存関係キャッシュファイルを設定するには、MATLAB の [プロジェクト] タブの [環境] セクションで [詳細] をクリックします。[依存関係のキャッシュファイル] で、GraphML ファイルを参照して指定します。キャッシュファイルが存在しない場合、依存関係の分析を実行すると、プロジェクトによりキャッシュファイルが作成されます。

プロジェクトの依存関係キャッシュは、プログラムで作成および設定することもできます。

proj = currentProject;
proj.DependencyCacheFile = "work/dependencyanalysis/projectcache.graphml";

変更をコミットしてプッシュし、GitHub と Jenkins で利用できるようにします。[プロジェクト] タブの [ソース管理] セクションで [コミット] をクリックしてから、[プッシュ] をクリックします。

Jenkins での依存関係キャッシュファイルの生成とアーカイブ

依存関係の分析キャッシュファイルを生成してアーカイブするように Jenkins プロジェクトを構成するには、Jenkins プロジェクトの構成ページで、次を行います。

新しいビルドステップを追加します。[Build] セクションで、[Add Build Step]、[Run MATLAB Command] を選択します。[Command] フィールドに、以下のスクリプトを入力します。
```
proj = openProject("ProjectAirframeExample.prj");
updateDependencies(proj);
```
このスクリプトは、MATLAB を起動し、MATLAB プロジェクトを読み込み、依存関係の分析を実行し、依存関係キャッシュファイルに結果をキャッシュします。
[Post-build Actions] セクションで、[Archive the artifacts] の [Files to archive] フィールドに、「work/dependencyanalysis/*.graphml」と入力します。ビルド後、Jenkins は GraphML ファイルを Jenkins ワークスペースからビルドアーカイブの場所にコピーします。

ローカルマシンでのキャッシュ共有による依存関係の分析の迅速化

頻繁にビルドを実行するように Jenkins を構成している場合、チームメンバーは、最後に成功したビルドに基づいてその作業用コピーを同期できます。チームメンバーは Git から設計の変更をチェックアウトし、関連付けられた依存関係キャッシュファイルをビルドアーカイブ領域から取得し、GraphML ファイルを指定された場所に配置します。

ローカルマシンで、MATLAB プロジェクトは事前設定された依存関係キャッシュファイルを使用して、インクリメンタルな依存関係の分析を実行します。これにより、名前の自動変更、プロジェクトの共有、影響分析の実行など、バックグラウンドで依存関係の分析を実行しているワークフローの時間を節約できます。

CI サーバーにおける、影響を受けるテストの実行と検定ランタイムの削減

CI サーバーでは、大規模なプロジェクトについて、事前設定された依存関係キャッシュを使用してインクリメンタルな影響分析を実行できます。影響を受けるテストのみを実行するようにプロジェクトビルドを構成すると、コード変更の検定時にランタイムを大幅に削減できます。

最後の変更によって影響を受けるテストのみを実行するように Jenkins プロジェクトを構成するには、[Build] セクションで、[Add Build Step]、[Run MATLAB Command] を選択します。[Command] フィールドに、以下のスクリプトを入力します。

proj = openProject("ProjectAirframeExample.prj");
[status,modifiedFiles] = system("git diff --name-only HEAD~1..HEAD :!resources");
updateDependencies(proj);
modifiedFiles = split(modifiedFiles);
modifiedFiles = modifiedFiles(1:(end-1))';
impactedFiles = listImpactedFiles(proj,modifiedFiles);
testFiles = findFiles(proj,Label="Test");
impactedTests = intersect(testFiles,impactedFiles);
 
runtests(impactedTests)

このスクリプトは、MATLAB を起動して MATLAB プロジェクトを読み込み、最後のコミットで変更されたファイルの一覧を取得し、影響分析を実行することで、変更の検定に必要なテストのサブセットを特定し、影響を受けるテストの一覧を実行します。

ワークフローの改善

いくつかの手順を追加で適用して、ワークフローを改善し、プロジェクトのビルドと検定を迅速化することができます。

GraphML ファイルと同様に、SLXC ファイルを生成およびアーカイブして再利用することで、シミュレーション時間を短縮することもできます。詳細については、シミュレーションを高速化するための Simulink キャッシュファイルの共有 (Simulink)を参照してください。
JFrog Artifactory などのデータベースまたはリポジトリ管理ツールを使用すれば、複数の Jenkins ビルドから SLXC ファイルと GraphML ファイルを容易に管理することができます。詳細については、https://jfrog.com/help/r/get-started-with-the-jfrog-platform/jfrog-artifactoryを参照してください。
関連付けられた依存関係キャッシュファイルを自動的に取得し、そのコピーを作業用コピーに配置するために、スクリプトを設定することができます。